Competition API

NOTE: The Competition services are still under development and are not yet available on Synapse.

Overview

The Competition API is designed to support open-access Synapse data analysis and modeling challenges. This framework provides tools for administrators to create new competitions in Synapse and manage the users and data objects associated with a competition. A competition owner can control access to competition resources and registration, as well as track user participation and evaluate submitted models. This API will support user-facing interfaces to monitor competitions including activity notifications and on-demand scoring and leaderboarding.

Data Models

Synapse Competitions are constructed around three primary objects: Competition, Participant, and Submission. These objects are defined by eponymous JSON schema files in the Synapse Repository Services.

Competition
Object representing a Synapse Competition

• ID - unique ID for the Competition
• eTag - optimistic concurrency flag; changes with each update
• ownerID - principal ID of the owner of the Competition
• name
• description
• contentSource - ID of the data source (e.g. entity) for the Competition (string)

• status - enum describing the state of the Competition, one of: PLANNED, OPEN, CLOSED, COMPLETED

Participant
Immutable object to represent a single user participating in a Competition. Competitions can have many users, and users can participate in many Competitions.

• ownerID - principal ID of the Participant
• competitionID
• createdOn - join date

Submission
Immutable object to represent an entity submission to a Competition. A participant can create many Submissions for a given Competition.

• ID - unique ID for the Submission
• name
• ownerID - principal ID of the Submission owner
• competitionID
• entityID - ID of the submitted entity
• version - specific entity version
• createdOn - submission date

SubmissionStatus
Object to track the status and score of a specific Submission. This object is generated at the time of submission, and can be modified by Competition administrators.

• submissionID
• eTag - optimistic concurrency flag; changes with each update
• status - enum describing the state of the Submission, one of: OPEN, CLOSED, SCORED, INVALID
• score - numerical score for this Submission (double between 0 and 1)

REST API

Competition

Participant

Submission

cURL Examples

Competition

• Create a Competition

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
      "status":"PLANNED",
      "description":"description",
      "name":"my first competition",
      "contentSource":"contentSource"
  }' https://repo-staging.prod.sagebase.org/repo/v1/competition

• Get a Competition

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json 
  'https://repo-staging.prod.sagebase.org/repo/v1/competition/1588317'

• Update a Competition

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
      "id":"1588317",
      "createdOn":"2013-01-16T16:30:56.727Z",
      "etag":"eed22bca-d88e-4b4a-8b1a-35dca7b7b8db",
      "status":"OPEN",
      "description":"description",
      "ownerId":"1588313",
      "name":"my first competition",
      "contentSource":"contentSource"
  }' https://repo-staging.prod.sagebase.org/repo/v1/competition/1588317

• Delete a Competition

  curl -i -k -H sessionToken:okxkSRyl3v0iIf0eutQfXA00 -H Accept:application/json -X DELETE 
  'https://repo-staging.prod.sagebase.org/repo/v1/competition/1588317'

Participant

• Create a Participant

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
      "ownerId":"123456"
  }' https://repo-staging.prod.sagebase.org/repo/v1/competition/987654/participant

• Delete a Participant

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -X DELETE 
  'https://repo-staging.prod.sagebase.org/repo/v1/competition/1588317/participant/1588313'

Submission

• Create a Submission

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
      "competitionId":"1588317",
      "entityId":"1588315",
      "versionNumber":"1",
      "name":"some-name"
  }' https://repo-staging.prod.sagebase.org/repo/v1/competition/submission

• Update a SubmissionStatus

  curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
      "id":"1589914",
      "modifiedOn":"2013-01-18T21:43:18.897Z",
      "etag":"13c88b1a-662c-4dd6-bb56-3976566516f7",
      "status":"SCORED",
      "score":0.42
  }' https://repo-staging.prod.sagebase.org/repo/v1/competition/submission/1589914/status

  
  
  

• Delete a Submission

  curl -i -k -H sessionToken:dPF2TqGUq121PR36AwJhXw00 -H Accept:application/json -X DELETE 
  'https://repo-staging.prod.sagebase.org/repo/v1/competition/submission/1589912'

Example Workflow

The following is a proposed workflow for interacting with the Competition Services. Please note that some components are still under development.

User Perspective

1. Find a Synapse Competition
2. Sign up as a Participant
3. Download relevant Synapse Entities referenced in Competition
4. Submit a Synapse entity to the Competition
5. Track status of personal Submissions and view global competition status/leaderboard
6. Earn achievements for participation / success

Owner/Admin Perspective

1. Create a Synapse Competition
   1. Fill in details, attach relevant Synapse entities
   2. Specify access requirements
   3. Specify open/close dates
2. Listen for Submissions (using messaging service)
   
   1. Download unscored Submissions
   2. Perform scoring
   3. Push scores back to each SubmissionStatus
3. Track user participation and publish competition status/leaderboard
4. Award achievements for user participation / success

Planned Improvements

The following features are planned but not yet implemented.

• Banned user lists
  Banned users should be prohibited from participating in one or more Competitions, and any Submissions by a banned user should be isolated from the general populations of Submissions.
  
  Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  
  
  
• Customizable Amazon Simple Notification Services messaging tools
  Competition administrators should have tools to configure a selective Amazon instance to listen for messages pertaining to Competitions which they own. These messages should be sent to a queue dedicated to Competitions.
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  
  
• Immutable copies of submitted Entities
  Once an Entity is submitted to a Competition, a static copy of that Entity should become the property of the Competition administration.
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  
  
• Administrator lists for Competitions
  Competitions should support administration by multiple users (rather than just the Competition owner). These admin lists should function as a lightweight ACL of sorts.
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  
  
• Multi-author Submissions
  Competitions should support team Submissions, where more than one Synapse user claims authorship of a given Submission.
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  
  
• Pagination support for fetching Participants and Submissions
  Currently the API supports fetching all Participants or all Submissions for a given Competition. To support high-volume Competitions, pagination shoudl be supported on these requests.
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.