JSON Scoreboard 2016

From ICPC-Contest Control Standard
Revision as of 07:36, 5 February 2016 by Clevengr (talk | contribs) (Introduction)

Introduction

This page describes a draft API for providing a scoreboard of an (ICPC) contest. It is based on the more encompassing Draft_CCS_REST_interface. This draft is proposed for implementation and use in the ICPC 2016 World Finals.

General design principles

The interface is implemented as a HTTP REST interface that outputs information in JSON format. The specific base URL will be dependent on the server (main CCS or CDS) providing the service and will be indicated as baseurl. 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:

Name Type Required? Description
label string yes label of the problem in the contest, typically a single capitalized letter
shortname string yes brief name of the problem (restrict to, say, 10 characters?)
name string yes name of the problem
color string no color of this problem (e.g. on the scoreboard), specified in HTML hexadecimal or HTML color name

Example

Request:

 GET http://example.com/problems

Returned data:

 [{"label":"A","shortname":"asteroids","name":"Asteroid Rangers","color":"blue"},
  {"label":"B","shortname":"bottles","name":"Curvy Little Bottles","color":"#ffaa00"},
  ...
 ]

GET baseurl/teams

Lists all teams.

Returns a JSON array, with each element an object describing a team, with the following elements:

Name Type Required? Description
number integer yes for WF2015 team number as used 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 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:

 [{"number":42,"name":"Shanghai Jiao Tong University","nationality":"CHN","affiliation":"Shanghai Jiao Tong University","group":"Asia",},
  {"number":11,"name":"CMU1","nationality":"USA","affiliation":"Carnegie Mellon University","group":"North America"},
  ...
 ]

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:

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 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 label, see below for the specification of each element

Each problem element within the scoreboard consists of:

Name Type Required? Description
label string yes label of the problem as in 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

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},
    {"label":"C","num_judged":2,"num_pending":0,"solved":true,"time":55},
    {"label":"D","num_judged":0,"num_pending":0,"solved":false},
    {"label":"E","num_judged":3,"num_pending":0,"solved":true,"time":205}
   ]},
  ...
 ]