Sign in
InOrbit
Docs
0%

Transports

Server-sent events

A request that answers with a stream of events, on routes ending in /events.

Shape

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": []}

Rules

  • The stream opens with one comment line, : open, the moment it is live, so a client knows it is connected before the first event. SSE clients skip comments.
  • 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 read timeout: the server sends a keep-alive comment every 15 seconds while there is nothing to say, so a client can treat 45 seconds of silence as a dropped connection. A stream lives at most 24 hours; then it ends with event: error and code unavailable, and you open it again.
  • The token must be valid when the stream opens; a stream is not cut when the token expires afterwards. It is cut when the key or API token behind it is revoked: within seconds, the stream ends with event: error and code unauthenticated.
  • A key, API token or person holds at most 32 open streams at once (event streams, sockets and MQTT connections together), an account 128. One more is refused before it opens with 429 rate_limited and Retry-After: 1; close one first. The account's event stream has a bound of its own: at most 10 open at once per account, all its keys together, answered 429 rate_limited past that.
  • A key opens the streams its scopes admit, like any other read: the account's events (GET /v1/events/events) need events:read. Opening a stream counts as one call of its operation in your usage; the events it carries cost nothing more.

From the reference

A stream's page in the API reference has Run and Stop under its fields instead of Send: Run opens the stream from your browser with the selected token, every event shows as it arrives, Stop closes it.

In a browser

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.

REST

A request and an answer, JSON both ways, on every route in the reference.

WebSocket

One socket that carries any call by name, several at once, with the same JSON as REST.