Contest_Data_Server_2019.mw

== Introduction ==

This page documents the CDS that was used at the 2019 World Finals and will be used at the 2020 World Finals. 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.
The [[Contest API 2020]] is fully supported.

As in 2018, all of the contests (e.g. test, dress rehearsal, finals) will be hosted from the start, allowing clients to connect in advance or continue to use data from a finished contest while the next one is configured. The CDS will be restarted on the morning of each contest with the final configuration as per the master schedule.

Note: 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.

== 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.

[[Contest Security]]
[[Contest Data]]

== Services ==

The following section describes all of the services that are available through the CDS.

=== Contest API ===

 <nowiki>https://cds/api/contests/<id></nowiki>
''Access: Authorized''

This is the root of the [[Contest API 2020]] interface, e.g. /api/contests/dress will return information about the dress rehearsal contest. The format of video has not changed - it is still MPEG-TS with the H.264 codec.

=== XML Event Feed ===
The XML event feed was removed before the 2019 World Finals.

=== Optimistic JSON Scoreboard ===
 <nowiki>https://cds/api/contests/<id>/optimisticScoreboard</nowiki>
''Access: Authorized''

Returns a JSON scoreboard as per the Contest API spec, but assumes that the most recent unjudged submission made on any problem is correct, and any previous unjudged submissions were incorrect. e.g. if a team has submitted four times and three were after the scoreboard freeze, this scoreboard will keep the same known judgement to the first (clearly incorrect in this case) and assume that the next two were wrong answers and the fourth was correct. If there is another submission, it will assume the fourth was incorrect and fifth is 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.

=== Video Channels ===

Each video channel connects to one team desktop, team video, or other video source at a time, but can be dynamically switched to another source. This allows a client to use a fixed url for the duration of the contest, and for another user (typically an admin or analyst) to switch which source the client is watching.

 <nowiki>http://cds/video/channel/[channelNum]</nowiki>
''Access: Public''