Server Sent Events

Server-Sent Events (eventsource)

Server-Sent Events (eventsource (over HTTPS) provides a simple and efficient channel through which a high volume of updates can pass. Although an additional library may be required depending on the servers' platform, it is a very light implementation.

Server-Sent Events require System 1 to implement a system to keep track of events and trigger the sending of data through this channel. This non-trivial implementation, together with the complexities of library support in various languages and frameworks compared with a straightforward JSON API implementation used in Polling and Webhooks is the reason that the other transport mechanisms are provided.

The responsibility is on the client to reestablish a connection to the server and inform it of the last retrieved record in order to continue the stream, which is closer to polling than to webhooks.

Response grammar / example:

/stream?afterTimestamp=Date(b)&afterId={d97f73fb-4718-48ee-a6a9-9c7d717ebd85}
->
event: itemupdate
data: <item>

Only the <item> from the <response> is required here, and is passed as "data" (the Server-Sent Event specification of "data", which is different from the "data" part of the item). The explicit paging used with polling and webhooks is made redundant as this is a continuous stream over one connection.

The event type is always set to "itemupdate", as the state of each item is set with the "state" field consistent with polling.

Server-Sent Events Example

An example stream is below:

/stream?afterTimestamp=Date(a)&afterId={a97f73fb-4718-48ee-a6a9-9c7d717ebd85}
->
event: itemupdate
data: {
   state: 'updated',
   kind: "session",
   id: "{c15814e5-8931-470c-8a16-ef45afedaece}",
   modified: Date(a),
   data: {
       lat: 51.5072,
       lng: -0.1275,
       name: 'Acrobatics with Dave',
       clubId: "{fc1f0f87-0538-4b05-96a0-cee88b9c3377}"
   }

event: itemupdate
data: {
   state: 'deleted',
   kind: "session",
   id: "{d97f73fb-4718-48ee-a6a9-9c7d717ebd85}",
   modified: Date(b)
}