Analyst_extension_of_Contest_API.mw

'''This is an early draft of extensions to the [[Contest API]] to support analyst data'''

Section names match those in [[Contest API]]. New sections (i.e. sections that do not appear in parent document) should simply be added. Existing but empty sections are only there for structure (i.e. to properly place a subsection). If edits are needed in an existing section there will be a comment within square brackets ([, ]) describing the changes needed.

== Interface specification ==

=== Types of endpoints ===

[ Add commentary-messages and edit-activities to Live data list ]

=== Teams ===

[ Add elements below to team object ]

{| class="wikitable"
|-
! Name
! Type
! Required?
! Nullable?
! Source @WF
! Description
|-
| main_language
| ID
| no
| yes
| Analysts
| identifier of the main [[Contest_API#Languages | programming language]] used by the team
|-
| latest_problem
| ID
| no
| yes
| Analysts
| identifier of the latest [[Contest_API#Problems | problem]] worked on by the team that they have not solved
|-
| latest_edit_contest_time
| RELTIME
| depends
| depends
| Analysts
| contest time of latest edit on unsolved problem. Required (and not null) iff <tt>latest_problem</tt> is present (and not null)
|}

=== Commentary messages ===

Provides commentary on events in the current contest.

The following endpoints are associated with commentary:
{| class="wikitable"
|-
! Endpoint
! Mime-type
! Required?
! Source @WF
! Description
|-
| /contests/<id>/commentary-messages
| application/json
| no
| Analysts
| JSON array of all messages with elements as defined in the table below
|-
| /contests/<id>/commentary-messages/<id>
| application/json
| no
| Analysts
| JSON object of a single message with elements as defined in the table below
|}

JSON elements of language objects:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Nullable?
! Source @WF
! Description
|-
| id
| ID
| yes
| no
| Analysts
| identifier of the message
|-
| team_id
| ID
| yes
| yes
| Analysts
| identifier of the [[Contest_API#Teams | team]] the message is related to
|-
| problem_id
| ID
| yes
| yes
| Analysts
| identifier of the [[Contest_API#Problems | problem]] the message is related to
|-
| submission_id
| ID
| yes
| yes
| Analysts
| identifier of the [[Contest_API#Submissions | submission]] the message is related to
|-
| priority
| ORDINAL
| yes
| no
| Analysts
| priority of the message. Lower values are higher priority
|-
| text
| string
| yes
| no
| Analysts
| plain text message
|-
| time
| TIME
| yes
| no
| Analysts
| time when commentary was made
|-
| contest_time
| RELTIME
| yes
| no
| Analysts
| contest time when commentary was made
|}

==== Access restrictions at WF ====

No access restrictions apply to a GET on this endpoint.

=== Edit Activities ===

Provides information about what teams are editing which problems when.

The following endpoints are associated with editing activities:
{| class="wikitable"
|-
! Endpoint
! Mime-type
! Required?
! Source @WF
! Description
|-
| /contests/<id>/edit-activities
| application/json
| no
| Analysts
| JSON array of all edit activities with elements as defined in the table below
|-
| /contests/<id>/edit-activities/<id>
| application/json
| no
| Analysts
| JSON object of a single edit activity with elements as defined in the table below
|}

JSON elements of edit activity objects:
{| class="wikitable"
|-
! Name
! Type
! Required?
! Nullable?
! Source @WF
! Description
|-
| id
| ID
| yes
| no
| Analysts
| identifier of the edit activity
|-
| team_id
| ID
| yes
| no
| Analysts
| identifier of the [[Contest_API#Teams | team]] doing the edit
|-
| problem_id
| ID
| yes
| yes
| Analysts
| identifier of the [[Contest_API#Problems | problem]] being edited. Null iff it's unknown what problem the edit was for
|-
| language_id
| ID
| yes
| yes
| Analysts
| identifier of the [[Contest_API#Languages | language]] being used in the edit. Null iff it's unknown what languages was used (or it is not one of the contest languages) 
|-
| line_count
| integer
| yes
| no
| Analysts
| number of lines in file being edited
|-
| diff_line_count
| integer
| yes
| no
| Analysts
| number of lines in diff of file being edited
|-
| file_size_bytes
| integer
| yes
| no
| Analysts
| file size of file being edited in bytes
|-
| time
| TIME
| yes
| no
| Analysts
| time of when edit was made
|-
| contest_time
| RELTIME
| yes
| no
| Analysts
| contest time of when edit was made
|}

==== Access restrictions at WF ====

No access restrictions apply to a GET on this endpoint.

=== Scoreboard ===

[ Add elements below to problem object ]

{| class="wikitable"
|-
! Name
! Type
! Required?
! Nullable?
! Source @WF
! Description
|-
| language_id
| ID
| no
| yes
| Analysts
| identifier of [[Contest_API#Languges | language]] used for last submission
|-
| potential
| object
| no
| yes
| Analysts
| JSON object as specified in the rows below
|-
| potential.rank
| integer
| depends
| no
| Analysts
| rank that the team would get if they solved this problem now. Required iff potential is present. 
|-
| potential.before
| integer
| depends
| no
| Analysts
| how many more minutes the team would reach the rank above by solving this problem assuming no other problems are solved. Required iff potential is present. 
|}

=== Event Feed ===

==== Feed format ====

[ Add entry below to API endpoint table ]

{| class="wikitable"
|-
! Event
! API Endpoint
|-
| commentary-messages
| /contests/<id>/commentary-messages/<id>
|}