JSON_Event_Feed.mw

This page describes a draft for a JSON event feed.

'''This page is deprecated, the JSON event feed is now included in the [[Draft_CCS_REST_interface#/event-feed | CSS REST interface]] specification.'''

== Getting the feed ==

The event feed is served over HTTPS at the `/event-feed` endpoint.

Access control uses the same [[Draft_CCS_REST_interface#Roles | user roles]] as defined for the REST API.

=== Feed options ===

==== Filtering events ====

If a client only wants some events the feed can be filtered with the "events" URL argument:

 /event-feed?events=submissions,teams

If not specified all events will be sent. If specified only the listed events will be sent.

==== Notification only ====

If a client does not want the "data" part of events this can be removed with the "no-data" URL argument:

 /event-feed?no-data

If not specified all events will include data. If specified the <tt>data</tt> attribute and its contents will not be present for any event.

==== Feed starting point ====

If a client wants data from some point in time this can be done with the "timestamp" URL argument:

 /event-feed?timestamp=2014-06-25T11%3A22%3A05.034%2B01

If specified the event feed will include all events strictly ''after'' the specified timestamp. If not specified the event feed will include all events from the beginning of the feed.

Timestamps in the future are allowed.

Timestamps are given as  [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] extended combined date/time format with timezone: <tt>yyyy-mm-ddThh:mm:ss(.uuu)?[+-]zz(:mm)?</tt> (or timezone <tt>Z</tt> for UTC). Specifically, they are given in the same format as the '''timestamp'''s in the feed. This means that if a client copies the timestamp of an event and uses that for the timestamp URL argument it will get all events after that event. This is useful e.g. if a client is disconnected and want to continue where it left off.

Multiple requests of the event feed for the same period must return equivalent events (excluding heartbeat events), including historical timestamps and configuration changes. The system might contain the same heartbeat events every time, but it is not required to.

== Feed format ==

The feed is served as [http://specs.okfnlabs.org/ndjson/ Newline delimited JSON], with every event as its own JSON object.

The general format for events is:
 {"event": "<event type>", "id": "<id>, "endpoint": "<API endpoint>", "timestamp": "<timestamp>", "data": <data from endpoint> }

This document uses the terms "element" and "collection". A collection is a list
of elements. An element corresponds to a single object (run, judgement,
language, team, etc.).

{| class="wikitable"
|-
! Name
! Description
! Format
|-
| event
| Name of the event. Used for filtering. 
| One of '''contests''', '''languages''', '''problems''', '''test-cases''', '''teams''', '''universities''', '''groups''', '''judgement-types''', '''submissions''', '''submission-files''', '''judgements''', '''runs''', '''clarifications'''.
|-
| id
| ID for the object that's being updated. Always present if event relates to element, never present if event relates to collection.
| String consisting of characters <tt>[a-zA-Z0-9-_]</tt> of length at most 36 and not starting with a <tt>-</tt> (dash).
|-
| endpoint
| URL for corresponding API endpoint. A GET from this URL would return exactly what's in the '''data''' element.
| URL
|-
| timestamp
| Time for the event. Some events will have internal timestamp in the data section. This timestamp might not agree with that timestamp. The semantics of this timestamp is simply when the event was sent on the feed. 
| [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] extended combined date/time format with timezone: <tt>yyyy-mm-ddThh:mm:ss(.uuu)?[+-]zz(:mm)?</tt> (or timezone <tt>Z</tt> for UTC).
|-
| data
| The exact data that would be returned if calling the corresponding API endpoint at this time.
| JSON object as defined by the [[Draft_CCS_REST_interface#Roles | REST API]].
|}

Events are guaranteed to come in timestamp order and timestamps are guaranteed to be unique. (Note though that this only applies to the event feed timestamp. Some events might have timestamps inside the "data" value, those might be different and specifically out of order).

Every event with a corresponding API endpoint maps to either a collection or an element in a collection. (The '''contests''' event is a special case. It could be argued that it is an element, and in any case it is treated as an element). When an event is sent as an element, that can either be an insert (if the ID given has not been seen before, update (if the ID has been seen before) or delete (if the ID has been seen before but the data element is "null"). When an event is sent as a collection it is always a complete replace of the previous state. E.g. if we have already seen IDs A and B and are sent a collection with IDs A and C that means that B is deleted, C is added and A is potentially updated (depending on whether the new value for A given is different or not). Note that in this case elements that are not changed at all must still be included with no change.

== Events ==

For all the examples below the base URL used is "https://example.com/contests/wf2017".

Many of the examples below have newlines for readability. In an actual feed there would '''never''' be any newlines in an event, since the events are delivered as NDJSON.

For many events '''data''' is listed as required. This does not change the fact that '''data''' will be omitted if the <tt>notification-only</tt> setting is used.

=== Contests ===

;Event ID: contests
;Required elements: event, id, endpoint, timestamp, data
;Examples:
 {"event": "contests", "id": "wf2017", "endpoint": "https://example.com/contests/wf2017", "timestamp": "2017-07-18T10:00:00+01", "data":
   {"id":"wf2017","name":"2014 ICPC World Finals",
   "formal_name":"38th Annual World Finals of the ACM International Collegiate Programming Contest",
   "start_time":"2017-07-18T10:00:00+01","duration":"5:00:00","scoreboard_freeze_duration":"1:00:00","penalty_time":20}
 }

=== Languages ===

;Event ID: languages
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Examples:
Update all / initial set up:
 {"event": "languages", "endpoint": "https://example.com/contests/wf2017/languages", "timestamp": "2017-07-18T10:01:01+01", "data": [
   {"id":"1-java","name":"Java"},
   {"id":"cpp","name":"GNU C++"},
   {"id":"4358281971166881160","name":"Python"}
 ]}
Add:
 {"event": "languages", "id": "python3", "endpoint": "https://example.com/contests/wf2017/languages/python3", "timestamp": "2017-07-18T10:01:02+01", "data":
   {"id":"python3","name":"Python 3"},
 }
Update:
 {"event": "languages", "id": "4358281971166881160", "endpoint": "https://example.com/contests/wf2017/languages/4358281971166881160", "timestamp": "2017-07-18T10:01:03+01", "data":
   {"id":"4358281971166881160","name":"Python 2"}
 }
Delete:
 {"event": "languages", "id": "1-java", "endpoint": "https://example.com/contests/wf2017/languages/1-java", "timestamp": "2017-07-18T10:01:04+01", "data": null}

=== Problems ===

;Event ID: problems
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "problems", "endpoint": "https://example.com/contests/wf2017/problems", "timestamp": "2017-07-18T10:02:01+01", "data": [
   {"id":"10-asteroids","label":"A","shortname":"asteroids","name":"Asteroid Rangers","ordinal":1,"color":"blue","rgb":"#00f"},
   {"id":"B","label":"B","shortname":"bottles","name":"Curvy Little Bottles","ordinal":2,"color":"gray","rgb":"#808080"}
 ]}
Add:
 {"event": "problems", "id": "circles", "endpoint": "https://example.com/contests/wf2017/problems", "timestamp": "2017-07-18T10:02:02+01", "data": 
   {"id":"circles","label":"C","shortname":"circles","name":"Circles","ordinal":3,"color":"red","rgb":"#f00"}
 }
Update:
 {"event": "problems", "id": "10-asteroids", "endpoint": "https://example.com/contests/wf2017/problems", "timestamp": "2017-07-18T10:02:03+01", "data": 
   {"id":"10-asteroids","label":"A","shortname":"asteroids","name":"Asteroid Rangers","ordinal":1,"color":"orange","rgb":"#f0b034"}
 }
Delete:
 {"event": "problems", "id": "circles", "endpoint": "https://example.com/contests/wf2017/problems", "timestamp": "2017-07-18T10:02:04+01", "data": null}

=== Test cases ===

;Event ID: test-cases
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "test-cases", "endpoint": "https://example.com/contests/wf2017/problems/10-asteroids/test_cases", "timestamp": "2017-07-18T10:03:01+01", "data": [
   {"id":"10-asteroids-1","problem_id":"10-asteroids","ordinal":1,"description":"Test corner case of zero input", "sample":false,"input":"<base64_string>","answer":"<base64_string>"}
   {"id":"10-asteroids-2","problem_id":"10-asteroids","ordinal":2,"description":"Test corner case of max input", "sample":false,"input":"<base64_string>","answer":"<base64_string>"}
 ]}
Add:
 {"event": "test-cases", "id": "10-asteroids-3", "endpoint": "https://example.com/contests/wf2017/problems/10-asteroids/test_cases/10-asteroids-3", "timestamp": "2017-07-18T10:03:02+01", "data": 
   {"id":"10-asteroids-3","problem_id":"10-asteroids","ordinal":3,"description":"Random large cases", "sample":false,"input":"<base64_string>","answer":"<base64_string>"}
 }
Update:
 {"event": "test-cases", "id": "10-asteroids-2", "endpoint": "https://example.com/contests/wf2017/problems/10-asteroids/test_cases/10-asteroids-2", "timestamp": "2017-07-18T10:03:03+01", "data": 
   {"id":"10-asteroids-2","problem_id":"10-asteroids","ordinal":2,"description":"Test corner case of min input", "sample":false,"input":"<base64_string>","answer":"<base64_string>"}
 }
Delete:
 {"event": "test-cases", "id": "10-asteroids-2", "endpoint": "https://example.com/contests/wf2017/problems/10-asteroids/test_cases/10-asteroids-2", "timestamp": "2017-07-18T10:03:04+01", "data": null}

=== Teams ===

;Event ID: teams
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "teams", "endpoint": "https://example.com/contests/wf2017/teams", "timestamp": "2017-07-18T10:04:01+01", "data": [
   {"id":"abc123","label":"123","icpc_id":"201433","name":"Shanghai Tigers","institution_id":"inst123"},
   {"id":"11","label":"11","name":"CMU1","institution_id":"inst105"}
 ]}
Add:
 {"event": "teams", "id": "12", "endpoint": "https://example.com/contests/wf2017/teams/12", "timestamp": "2017-07-18T10:04:02+01", "data":
   {"id":"12","label":"12","icpc_id":"65243","name":"Balloons'R'us","institution_id":"kth.se"}
 }
Update:
 {"event": "teams", "id": "11", "endpoint": "https://example.com/contests/wf2017/teams/11", "timestamp": "2017-07-18T10:04:03+01", "data":
   {"id":"11","label":"11","icpc_id":"1234","name":"CMU1","institution_id":"inst105"}
 }
Delete:
 {"event": "teams", "id": "abc123", "endpoint": "https://example.com/contests/wf2017/teams/abc123", "timestamp": "2017-07-18T10:04:04+01", "data": null}

=== Universities ===

;Event ID: universities
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "universities", "endpoint": "https://example.com/contests/wf2017/universities", "timestamp": "2017-07-18T10:05:01+01", "data": [
   {"id":"inst123","icpc_id":"433","name":"Shanghai Jiao Tong U.","formal_name":"Shanghai Jiao Tong University","group_id":"asia-74324325532"},
   {"id":"inst105","name":"Carnegie Mellon University","country":"USA","group_id":"8"}
 ]}
Add:
 {"event": "universities", "id": "kth.se", "endpoint": "https://example.com/contests/wf2017/universities/kth.se", "timestamp": "2017-07-18T10:05:02+01", "data":
   {"id":"kth.se","icpc_id":"360","name":"KTH","formal_name":"KTH Royal Institute of Technology","group_id":"europe"},
 }
Update:
 {"event": "universities", "id": "inst123", "endpoint": "https://example.com/contests/wf2017/universities/inst123", "timestamp": "2017-07-18T10:05:03+01", "data":
   {"id":"inst123","icpc_id":"433","name":"Shanghai Jiao Tong U.","formal_name":"Shanghai Jiao Tong University","country":"CHN","group_id":"asia-74324325532"},
 }
Delete:
 {"event": "universities", "id": "inst105", "endpoint": "https://example.com/contests/wf2017/universities/inst105", "timestamp": "2017-07-18T10:05:03+01", "data": null}

=== Groups ===

;Event ID: groups
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "groups", "endpoint": "https://example.com/contests/wf2017/groups", "timestamp": "2017-07-18T10:06:01+01", "data": [
   {"id":"asia-74324325532","icpc_id":"7593","name":"Asia"}
   {"id":"europe","icpc_id":"7594","name":"Europe"}
 ]}
Add:
 {"event": "groups", "id": "north-america", "endpoint": "https://example.com/contests/wf2017/groups/north-america", "timestamp": "2017-07-18T10:06:02+02", "data":
   {"id":"north-america","name":"North America"}
 }
Update:
 {"event": "groups", "id": "north-america", "endpoint": "https://example.com/contests/wf2017/groups/north-america", "timestamp": "2017-07-18T10:06:03+02", "data":
   {"id":"north-america","icpc_id":"7595""name":"North America"}
 }
Delete:
 {"event": "groups", "id": "asia-74324325532", "endpoint": "https://example.com/contests/wf2017/groups/asia-74324325532", "timestamp": "2017-07-18T10:06:03+02", "data": null}

=== Judgement types ===

;Event ID: judgement-types
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "judgement-types", "endpoint": "https://example.com/contests/wf2017/judgement-types", "timestamp": "2017-07-18T10:07:01+01", "data": [
   {"id":"CE","label":"CE","name":"Compiler Error","penalty":false,"solved":false},
   {"id":"0357c4a9-6983-45d7-8080-90d24c5511ea","label":"AC","name":"Accepted","penalty":false,"solved":true}
 ]}
Add:
 {"event": "judgement-types", "id": "WA", "endpoint": "https://example.com/contests/wf2017/judgement-types/WA", "timestamp": "2017-07-18T10:07:02+01", "data": 
   {"id":"WA","label":"WA","name":"Wrong Answer","penalty":true,"solved":false},
Update:
 {"event": "judgement-types", "id": "CE", "endpoint": "https://example.com/contests/wf2017/judgement-types/CE", "timestamp": "2017-07-18T10:07:03+01", "data": 
   {"id":"CE","label":"CE","name":"Compile Error","penalty":true,"solved":false},
 }
Delete:
 {"event": "judgement-types", "id": "0357c4a9-6983-45d7-8080-90d24c5511ea", "endpoint": "https://example.com/contests/wf2017/judgement-types/0357c4a9-6983-45d7-8080-90d24c5511ea", "timestamp": "2017-07-18T10:07:04+01", "data": null}

=== Submissions ===

;Event ID: submissions
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "submissions", "endpoint": "https://example.com/contests/wf2017/submissions", "timestamp": "2017-07-18T10:08:01+01", "data": [
   {"id":"wf2017-32163123xz3132yy","label":"187","team_id":"abc123","problem_id":"10-asteroids",
   "language_id":"1-java","time":"2014-06-25T11:22:05.034+01","contest_time":"1:22:05.034","entry_point":"Main"}
 ]}
Add:
 {"event": "submissions", "id": "wf2017-32163123xz3132yy", "endpoint": "https://example.com/contests/wf2017/submissions/wf2017-32163123xz3132yy", "timestamp": "2017-07-18T10:08:02+01", "data": 
   {"id":"wf2017-32163123xz3132yy","label":"187","team_id":"abc123","problem_id":"10-asteroids",
   "language_id":"1-java","time":"2014-06-25T11:22:05.034+01","contest_time":"1:22:05.034","entry_point":"Main"}
 }

=== Submission files ===

;Event ID: submission-files
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "submission-files", "endpoint": "https://example.com/contests/wf2017/submission-files", "timestamp": "2017-07-18T10:09:01+01", "data": [
   {"id":"d079c12d-98ce-4bb7-8097-ae083b45feb4","submission_id":"wf2017-32163123xz3132yy","filename":"a.java","source":"<base64_string>","main":true},
   {"id":"18e44041-8caf-4d77-8864-f5584f1ddfed","submission_id":"wf2017-32163123xz3132yy","filename":"helper.java","source":"<base64_string>","main":false}
 ]}
Add:
 {"event": "submission-files", "id": "fc5344b2-657e-11e7-907b-a6006ad3dba0", "endpoint": "https://example.com/contests/wf2017/submission-files/fc5344b2-657e-11e7-907b-a6006ad3dba0", "timestamp": "2017-07-18T10:09:02+01", "data": 
   {"id":"fc5344b2-657e-11e7-907b-a6006ad3dba0","submission_id":"wf2017-32163123xz3132yy","filename":"kattio.java","source":"<base64_string>","main":false}
 }

=== Judgements ===

;Event ID: judgements
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "judgements", "endpoint": "https://example.com/contests/wf2017/judgements", "timestamp": "2017-07-18T10:10:01+01", "data": [
   {"id":"189549","submission_id":"wf2017-32163123xz3132yy","judgement_type_id":"CE","time":"2014-06-25T11:22:48.427+01","contest_time":"1:22:48.427"}
 ]}
Add:
 {"event": "judgements", "id": "189550", "endpoint": "https://example.com/contests/wf2017/judgements/189550", "timestamp": "2017-07-18T10:10:02+01", "data":
   {"id":"189550","submission_id":"wf2017-32163123xz3132yy","judgement_type_id":"CE","time":"2014-06-25T11:22:48.427+01","contest_time":"1:22:48.427"}
 }

=== Runs ===

;Event ID: runs
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "runs", "endpoint": "https://example.com/contests/wf2017/runs", "timestamp": "2017-07-18T10:11:01+01", "data": [
   {"id":"1312","submission_judgement_id":"189549","test_case_id":"10-asteroids-28","judgement_type_id":"0357c4a9-6983-45d7-8080-90d24c5511ea",
   "output":"<base64_string>","time":"2014-06-25T11:22:42.420+01","contest_time":"1:22:42.420"}
 ]}
Add:
 {"event": "runs", "id": "1313", "endpoint": "https://example.com/contests/wf2017/runs/1313", "timestamp": "2017-07-18T10:11:01+01", "data": 
   {"id":"1313","submission_judgement_id":"189549","test_case_id":"10-asteroids-28","judgement_type_id":"0357c4a9-6983-45d7-8080-90d24c5511ea",
   "output":"<base64_string>","time":"2014-06-25T11:22:42.420+01","contest_time":"1:22:42.420"}
 }

=== Clarifications ===

;Event ID: clarifications
;Required elements: event, endpoint, timestamp, data
;Optional elements: id
;Example:
Update all / initial set up:
 {"event": "clarifications", "endpoint": "https://example.com/contests/wf2017/clarifications", "timestamp": "2017-07-18T10:12:01+01", "data": [
   {"id":"wf2017-1","reply_to_id":null,"team_id":null,"problem_id":null,"text":"Do not touch anything before the contest starts!",
   "from_jury":true,"to_all_teams":true,"time":"2014-06-25T11:59:27.543+01","contest_time":"-0:15:32.457"}
 ]}
Add:
 {"event": "clarifications", "endpoint": "https://example.com/contests/wf2017/clarifications", "timestamp": "2017-07-18T10:12:02+01", "data":
   {"id":"wf2017-8","reply_to_id":"wf2017-5","team_id":null,"problem_id":"10-asteroids","text":"Does bouncing means bounce to the grid above the current one? Yes",
   "from_jury":true,"to_all_teams":true,"time":"2014-06-25T12:43:02.037+01","contest_time":"2:28:02.037"}
 }

=== Heartbeat ===

The event feed is guaranteed to send some data at least every 120 seconds. If no other event is sent, a heartbeat will be.

The heartbeat event does *not* have a corresponding API endpoint, so the endpoint and data keys are missing.

;Event ID: heartbeat
;Required elements: event, timestamp
;Example:
 {"event": "heartbeat", "timestamp": "2017-07-18T10:13:01+01"}