Events

Various resources will include an event stream. For those resources, there will be an endpoint defined from which the events can be retrieved via a GET request.

Request:

GET .../events?after-event-id={after}

{after} is optional (-1 assumed if omitted). Only events whose id is greater than this value will be returned.

Thus, each time a response is received, you should store the id and supply it in the next request.

This is a long-polling request meaning the response won't necessarily be sent straight away. After some time, an empty response may be sent. At which point, the client should repeat the same request. More than one event may be returned.

In general, one of the following things will happen:

• When the request is made, there are already events which match the criteria. The response will be returned immediately and will consist of these events.
• When the request is made, there are no events matching the criteria. The response will not be returned until one of the following occurs:
  • One or more new events are fired: these will be returned.
  • The request times out: an empty list is sent ("[]").

In case of the empty list, the client should immediately repeat the request. Otherwise, the client should deal with the events in ascending order of id, and then repeat the request, but with {after} set to the largest id which was received.

If more than 10 events land in the range you ask for, you will only be sent the most recent 10 events. If this has occurred, it will usually mean you have not been requesting for events often enough. If you get out of sync, you will need to grab the state from scratch.

Response:

[
    {
        "id" : 0,
        "event" : { ... }
    },
    ....
]

The structure of the event object is defined by the corresponding resource.