JSON_Scoreboard_2016.mw

== Introduction ==

This page describes an API for providing a scoreboard of an (ICPC) contest.
It is based on the more encompassing [[Draft_CCS_REST_interface]].
The API described on this page is planned for use in the ICPC 2016 World Finals.

== General design principles ==

The interface is implemented as a HTTP REST interface that outputs information in [https://en.wikipedia.org/wiki/JSON JSON] format. The specific base URL will be dependent on the server (main CCS or CDS) providing the service and will be indicated as <tt>baseurl</tt>.
None of the calls in the current specification take arguments.

Access to (parts of) the API is optionally controlled by HTTP authentication. This provides a standard and flexible method, while the user one authenticates as can be used for fine-grained access control to specific bits.

== Interface specification ==

=== GET baseurl/problems ===

Lists problems in the current contest.

Returns a JSON array, with each element an object describing a problem, with the following elements:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Description
|-
| id
| integer
| yes
| numeric identifier, determines order of problems
|-
| label
| string
| yes
| label of the problem in the contest, typically a single capitalized letter; for WF2016: label for id 1='A', label for id 2='B', etc.
|-
| short_name
| string
| yes
| brief name of the problem (restrict to, say, 10 characters?)
|-
| name
| string
| yes
| name of the problem
|-
| rgb
| string
| no
| hexadecimal RGB value of problem color as specified in [http://en.wikipedia.org/wiki/Web_colors#Hex_triplet HTML hexadecimal colors], e.g. '#AC00FF' or '#fff'
|-
| color
| string
| no
| human readable color description associated to the RGB value
|}

==== Example ====

Request:
  GET http://example.com/problems
Returned data:
  [{"id":1,"label":"A","short_name":"asteroids","name":"Asteroid Rangers","rgb":"#00f","color":"blue"},
   {"id":2,"label":"B","short_name":"bottles","name":"Curvy Little Bottles","rgb":"#808080","color":"gray"},
   ...
  ]

=== GET baseurl/teams ===

Lists all teams.

Returns a JSON array, with each element an object describing a team, with the following elements:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Description
|-
| id
| integer
| yes for WF2015
| team identifier; seat number in the World Finals
|-
| name
| string
| yes
| name of the team
|-
| affiliation
| string
| yes for WF
| name of university or other entity that team is affiliated to (may be same as name at WFs)
|-
| nationality
| string
| yes for WF
| [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 ISO 3-letter code] of the team's nationality
|-
| group
| string
| yes for WF
| group this team is part of (in ICPC WFs these are the super-regions, such as Europe)
|}

==== Example ====

Request:
  GET http://example.com/teams
Returned data:
  [{"id":42,"name":"Shanghai Tigers","nationality":"CHN","affiliation":"Shanghai Jiao Tong University","group":"Asia"},
   {"id":11,"name":"CMU1","nationality":"USA","affiliation":"Carnegie Mellon University","group":"North America"},
   ...
  ]

Note that in the World Finals, the team name will be set to the university affiliation.

=== GET baseurl/scoreboard ===

Provides the scoreboard of the current contest.

Returns a JSON array where each element is an object that represents a row for one team. The array is
sorted according to rank and alphabetical on team name within identically ranked teams.
Each row object contains:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Description
|-
| rank
| integer
| yes
| rank of this team, 1-based and duplicate in case of ties
|-
| team
| integer
| yes
| identifier of the team as in [[#GET baseurl/teams|teams API call]].
|-
| score
| object
| yes
| object (for possible extension to other scoring methods) containing integer elements "num_solved" and "total_time"
|-
| problems
| array
| yes
| array of problems with scoring data sorted on problem id, see below for the specification of each element
|}
Each problem element within the scoreboard consists of:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Description
|-
| label
| string
| yes
| label of the problem as in [[#GET baseurl/problems|problems API call]].
|-
| num_judged
| integer
| yes
| number of judged submissions (including possibly a final correct one)
|-
| num_pending
| integer
| yes
| number of pending submissions (either queued or due to freeze)
|-
| solved
| boolean
| yes
| whether the team solved this problem
|-
| time
| integer
| yes
| present if solved, minutes into the contest when solved by team
|-
| first_to_solve
| boolean
| yes
| present if solved, indicates whether this team was the first to solve this problem
|}

==== Example ====

Request:
  GET http://example.com/scoreboard
Returned data:
  [{"rank":1,"team":42,"score":{"num_solved":3,"total_time":340},
    "problems":[
     {"label":"A","num_judged":3,"num_pending":1,"solved":false},
     {"label":"B","num_judged":1,"num_pending":0,"solved":true,"time":20,"first_to_solve":true},
     {"label":"C","num_judged":2,"num_pending":0,"solved":true,"time":55,"first_to_solve":false},
     {"label":"D","num_judged":0,"num_pending":0,"solved":false},
     {"label":"E","num_judged":3,"num_pending":0,"solved":true,"time":205,"first_to_solve":false}
    ]},
   ...
  ]