Server-sent events

ShapeCopy Anchor Link

A route whose path ends in /events answers text/event-stream. Each event's data: is one JSON object, the same shape a REST answer of that type would have.

curl -N https://api.inorbit.hr/v1/<resource>/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

data: {"…": "…"}

data: {"…": "…"}

event: error
data: {"code": "unavailable", "error": "…", "details": []}

RulesCopy Anchor Link

• The stream carries data: events until the server ends it. A failure arrives as one event: error whose data is the error envelope; the stream is then over and the client decides whether to reconnect.
• There is no Last-Event-ID; a reconnect starts fresh. A route that supports resuming says so in the reference.
• The gateway gives a stream no timeout. Keep the connection open as long as you read; a client that stops reading is disconnected by its own transport, not by the API.
• The token must be valid when the stream opens; a stream is not cut when the token expires afterwards.

In a browserCopy Anchor Link

EventSource cannot set the Authorization header. A browser client uses fetch with Accept: text/event-stream and reads the body as a stream, or the WebSocket, where the token is sent once.