Note: The Competition services described here 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 - user ID of the owner of the Competition
- name
- description
- contentSource - descriptor of the data source 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 - user 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.
- ownerID - user 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 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 (long)
REST API
Competition
| URL | HTTP Type | Description |
|---|---|---|
| /competition | POST | Create a new Synapse Competition |
| /competition/{competitionId} | GET | Fetch a Synapse Competition |
| /competition/{competitionId} | PUT | Update a Synapse Competition |
Participant
| URL | HTTP Type | Description |
|---|---|---|
| /competition/{competitionId}/participant | POST | Join as a new Participant in the Competition specified by competitionId. |
Submission
| URL | HTTP Type | Description |
|---|---|---|
| /competition/submission | POST | Create a new Synapse Submission |
| /competition/submission/{submissionId} | GET | Fetch a Synapse Submission |
| /competition/submission/{submissionId} | PUT | Update a Synapse Submission |
Example Workflow