NOTE: The Competition services are still under development and are not yet available on Synapse.
| Table of Contents |
|---|
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.
...
- 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 | Request Parameters |
|---|---|---|---|
| /competition | POST | Create a new Competition | userId (String) |
| /competition/{competitionId} | GET | Fetch Get a Competition | |
| /competition/{competitionId} | PUT | Update a Competition | userId (String) |
| /competition/{competitionId} | DELETE | Delete a Competition | userId (String) |
| /competition | GET | Batch Get Competitions (Paginated) | limit (long) |
| /competition/count | GET | Get the number of Competitions | |
| /competition/name/{name} | GET | Find a Competition by name |
Participant
| URL | HTTP Type | Description | Request Parameters |
|---|---|---|---|
| /competition/{competitionId}/participant | POST | Join as a new Participant in the Competition specified by competitionIda Participant in a Competition | userId (String) |
| /competition/{competitionId}/participant/{userId} | POST | Add another user as a Participant in a Competition. Requires admin rights on the Competition. | userId (String) |
| /competition/{competitionId}/participant/{userId} | GET | Get a Participant | |
| /competition/{competitionId}/participant/{userId} | DELETE | Delete a Participant | userId (String) |
| /competition/{competitionId}/participant/ | GET | Batch get Participants for a given Competition (Paginated) | |
| /competition/{competitionId}/participant/count | GET | Get the number of Participants in a given Competition |
Submission
| URL | HTTP Type | Description | Request Parameters |
|---|---|---|---|
| /competition/submission | POST | Create a new Submission. (and a corresponding SubmissionStatus object) | userId (String) |
| /competition/submission/{submissionId} | GET | Fetch Get a Submission | |
| /competition/submission/{submissionId}/status | GET | Get the status of a Submission | |
| /competition/submission/{submissionId}/status | PUT | Update the status of a Submission. | userId (String) |
| /competition/submission/{submissionId} | DELETE | Delete a Submission. Requires admin rights on the Competition. | userId (String) |
| /competition/{compId}/submission | GET | Batch get Submissions for a given Competition (Paginated). | userId (String) SubmissionStatusEnum (String) (optional) |
| /competition/{compId}/submission/count | GET | Get the number of Submissions for a given Competition |
Example Workflow
The following is a proposed workflow for interacting with the Competition Services. Please note that some components are still under development.
...
- Create a Synapse Competition
- Fill in details, attach relevant Synapse entities
- Specify access requirements
- Specify open/close dates
- Listen for Submissions (using messaging service)
- Download unscored Submissions
- Perform scoring
- Push scores back to each SubmissionStatus
- Track user participation and publish competition status/leaderboard
- Award achievements for user participation / success
Planned Additions
The following Competition Services features are planned but not yet implemented.
...