Contest Data Server 2018
This page documents the CDS version 2.0 that will be used at the 2018 World Finals. The primary change from previous years is support of the new Contest API. All services from past years are still available, but several have been removed from this page since they are now part of the official Contest API (see the complete list at the bottom of this page). If you find something 'missing' here, please check the API documentation first. If there is a previous endpoint that would be very hard for you to switch to the new interface in time for 2018 finals please ping John and Tim to discuss whether we can leave the old endpoint in place for one year.
Note that as part of the new Contest API's multi-contest support, each contest (e.g. test contests, dress rehearsal, finals) will be hosted at a separate URL path! For example, the dress rehearsal might be hosted at https://cds/api/contests/dress and the finals at https://cds/api/contests/final. This will allow us to configure all of the contests in advance and leave contests running longer than in past years to help clients test, but each client will need to remember to switch to the next contest URL when they're ready.
The Contest Data Server (or CDS) is a one-stop shop for external clients to obtain all onsite contest related information. This document contains information on the services (URLs) that are available from the CDS, what content is returned, and links to specs for the format of some files.
It's best to think of the CDS as an aggregator and gate keeper. It provides a single source for information and controls access, but most of the data is provided by other sources on the blue network, including the Contest Control System and data extracted from the Baylor CMS.
- URLs below are in the format "http://cds/xyz". The exact hostname or IP address for 'cds' will be provided once the network is setup onsite; contest machines configured by sysops will be able to lookup this hostname.
- Invalid URLs, parameters (e.g. teamNum=500), or missing images will return the standard HTTP status codes 404. Ditto for authentication and code 403.
Access & Authentication
Requests for access to the CDS must be made through the world finals technical director (John Clevenger) and must include contact information for during the finals. Many of the services will contain private information, so each client will be given a unique user id & password to connect to the CDS. Access to all secure services is via HTTPS. (HTTP access will be redirected)
To simplify security, access is provided via roles that each have access to different content. The defined roles are as follows:
- Public - Access only to data/services that are public contest info and can be shared externally at any time. These few services require no authentication.
- Authorized - Authorized access to public data/services that can be shared externally at any time.
- Analyst - Authorized + access to team backups and submission source.
- Balloon - Authorized + access to runs within the last hour if the team has less than 3 balloons.
- Blue - Full access to all data/services, typically someone within the contest network. (e.g. results during final hour)
- Admin - Full access + control authority.
Access builds somewhat logically, e.g. Blue users have access to everything that Analysts & Balloon have. The services below are marked with what access role is required.
The following section describes all of the services that are available through the CDS.
Contest API REST Interface
This is the root of the new contest API interface, e.g. /contests/dress will return information about the dress rehearsal contest.
XML Event Feed
For backward compatibility the CDS will still support the 2016 event feed as generated by the CCS: Event Feed 2016.
Clients without Blue access rights will receive a filtered event feed not containing submission judgments from the final hour.
Optimistic JSON Scoreboard
Returns a JSON scoreboard as defined here: JSON Scoreboard 2016
The optimistic scoreboard assumes that the last submission made on any problem during the freeze is solved. e.g. if a team has submitted three times after the scoreboard freeze, this scoreboard will assume that the first two were wrong answers and the third was correct.
This scoreboard may not be shown publicly unless it is clearly labelled as a possible projection! In reality the first submission might have been correct, or the third may still not be solved.
Contest RSS Feed (Draft)
Returns an RSS feed of solved submissions, e.g. "University of X solved problem Y!"
Clients without sufficient access rights will received a filtered RSS feed that does not contain submission judgments from the final hour.
Channels are a paired camera & screen video that can be changed on demand. It allows a client to use a fixed url for the duration of the contest, and for another user (typically an analyst) to switch which team the client is watching.
Returns video streams of the given channel, with content and format identical to the team webcam and desktop streams above.
Changes the given channel to output from the given team.
Previous endpoints that are now included as part Contest API include the following:
- Submission Source (Draft 2014 REST interface for source code fetching)
- Team backups
- Start time interface (Draft 2014 REST interface for contest start)
- JSON scoreboard
- Event feed
- Contest feed
- University logos
- Team logos
- Team registration videos
- Reaction videos
- Desktop streaming
- Webcam streaming
The format of these has not changed - it will still be MPEG-TS with the H.264 codec.