Contest_Start_Interface.mw

== Introduction ==

This page describes a '''draft''' interface for controlling the contest start time in a CCS. It is initially intended to be used by the [[CDS|Contest Data Server]] to allow an admin to control the start of a contest, but is meant to be reusable for other clients as well.

Usage notes:
* The interface is implemented as an HTTP REST interface.
* Basic authentication and HTTPS are required. User id/password is provided by the CCS and should be the same as the [[source code fetching interface|Draft 2014 REST interface for source code fetching]]
* The specific base URL will be dependent on the server providing the service and will be indicated as <tt>baseurl</tt>.
* Absolute times are always in decimal seconds since the Unix epoch: Jan 1, 1970 UTC.

== Interface specification ==

The URL for controlling the contest start time is always the same:
 <nowiki>https://baseurl/starttime</nowiki>

Changing the start time is always done via PUT, which is the only operation implemented for 2014. Options for a future GET interface are also listed.

When a PUT changes the value, the CCS must output a new <info> element to the event feed.

=== Interface ===

PUT HTTP body is application/json:
* { "starttime":1265335138.26 }
or:
* { "starttime":"undefined" }

HTTP response is:
* 200: if successful.
* 400: if the payload is invalid json, start time is invalid, etc.
* 401: if authentication failed.
* 403: if contest is already started
* 403: if setting to 'undefined' with less than 10s left to previous start time.
* 403: if setting to new (defined) start time with less than 30s left to previous start time.
* 403: if the new start time is less than 30s from now.

==== Future ====

GET HTTP body returns application/json:
* { "starttime":1265335138.26 }
or:
* { "starttime":"undefined" }