Difference between revisions of "JSON Scoreboard 2016"

From ICPC-Contest Control Standard
(Rename field "region" to more general "group" reflecting proposed/implemented change to XML feed.)
(GET baseurl/scoreboard: add "first_to_solve" attribute)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
  
This page describes a '''draft''' API for providing a scoreboard of an (ICPC) contest.
+
This page describes an API for providing a scoreboard of an (ICPC) contest.
 
It is based on the more encompassing [[Draft_CCS_REST_interface]].
 
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 ==
 
== General design principles ==
Line 24: Line 25:
 
! Required?
 
! Required?
 
! Description
 
! Description
 +
|-
 +
| id
 +
| integer
 +
| yes
 +
| numeric identifier, determines order of problems
 
|-
 
|-
 
| label
 
| label
 
| string
 
| string
 
| yes
 
| yes
| label of the problem in the contest, typically a single capitalized letter
+
| 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.
 
|-
 
|-
| shortname
+
| short_name
 
| string
 
| string
 
| yes
 
| yes
Line 39: Line 45:
 
| yes
 
| yes
 
| name of the problem
 
| 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
 
| color
 
| string
 
| string
 
| no
 
| no
| color of this problem (e.g. on the scoreboard), specified in [http://en.wikipedia.org/wiki/Web_colors HTML hexadecimal or HTML color name]
+
| human readable color description associated to the RGB value
 
|}
 
|}
  
Line 51: Line 62:
 
   GET http://example.com/problems
 
   GET http://example.com/problems
 
Returned data:
 
Returned data:
   [{"label":"A","shortname":"asteroids","name":"Asteroid Rangers","color":"blue"},
+
   [{"id":1,"label":"A","short_name":"asteroids","name":"Asteroid Rangers","rgb":"#00f","color":"blue"},
   {"label":"B","shortname":"bottles","name":"Curvy Little Bottles","color":"#ffaa00"},
+
   {"id":2,"label":"B","short_name":"bottles","name":"Curvy Little Bottles","rgb":"#808080","color":"gray"},
 
   ...
 
   ...
 
   ]
 
   ]
Line 68: Line 79:
 
! Description
 
! Description
 
|-
 
|-
| number
+
| id
 
| integer
 
| integer
 
| yes for WF2015
 
| yes for WF2015
| team number as used in the World Finals
+
| team identifier; seat number in the World Finals
 
|-
 
|-
 
| name
 
| name
Line 99: Line 110:
 
   GET http://example.com/teams
 
   GET http://example.com/teams
 
Returned data:
 
Returned data:
   [{"number":42,"name":"Shanghai Jiao Tong University","nationality":"CHN","affiliation":"Shanghai Jiao Tong University","group":"Asia",},
+
   [{"id":42,"name":"Shanghai Tigers","nationality":"CHN","affiliation":"Shanghai Jiao Tong University","group":"Asia"},
   {"number":11,"name":"CMU1","nationality":"USA","affiliation":"Carnegie Mellon University","group":"North America"},
+
   {"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 ===
 
=== GET baseurl/scoreboard ===
Line 136: Line 149:
 
| array
 
| array
 
| yes
 
| yes
| array of problems with scoring data, see below for the specification of each element
+
| 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:
 
Each problem element within the scoreboard consists of:
Line 170: Line 183:
 
| yes
 
| yes
 
| present if solved, minutes into the contest when solved by team
 
| 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
 
|}
 
|}
  
Line 180: Line 198:
 
     "problems":[
 
     "problems":[
 
     {"label":"A","num_judged":3,"num_pending":1,"solved":false},
 
     {"label":"A","num_judged":3,"num_pending":1,"solved":false},
     {"label":"B","num_judged":1,"num_pending":0,"solved":true,"time":20},
+
     {"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},
+
     {"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":"D","num_judged":0,"num_pending":0,"solved":false},
     {"label":"E","num_judged":3,"num_pending":0,"solved":true,"time":205}
+
     {"label":"E","num_judged":3,"num_pending":0,"solved":true,"time":205,"first_to_solve":false}
 
     ]},
 
     ]},
 
   ...
 
   ...
 
   ]
 
   ]

Latest revision as of 19:32, 28 March 2016

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

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

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 id, 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
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}
   ]},
  ...
 ]