[ADP-373] Server Side Events
Overview
Server Side Events (SSE) is one of the ways to provide clients with real-time notifications. SSE allows servers to push updates to the client over a single, long-lived HTTP connection. This mechanism is particularly useful for applications requiring timely updates, such as live feeds, notifications, or real-time data monitoring.
Guidance
Server Implementation
The API provider (server) MUST specify
Content-Type: text/event-streamin the response header to indicate that the response is a stream of events.The server SHOULD keep the connection open as long as possible to push updates to the client continuously.
Each event in the stream SHOULD follow the SSE format:
Data lines: Start with "data:" followed by the event data.
Event lines: Start with "event:" followed by the event name (optional).
ID lines: Start with "id:" followed by a unique identifier for the event (optional).
Retry lines: Start with "retry:" followed by the reconnection time in milliseconds (optional).
You MAY design a mechenism to terminate the connection in header.
Client Implementation
The API consumer (client) MUST specify
Accept: text/event-streamin the request header if it is requesting continuous server-side messages instead of a one-time request-response.The client SHOULD handle reconnections gracefully in case of network issues or server restarts.
The API consumer (browser client) SHOULD use the Fetch API with streaming support instead of the EventSource API, as the latter is considered outdated and less flexible.
Error Handling: The server SHOULD send an error event if an error occurs during the stream. The client can use this to handle errors appropriately.
Termination Header: The server SHOULD include a custom header X-SSE-Terminate with the value true to indicate that the connection should be terminated.
Security Considerations
Ensure proper authorization mechanisms are in place. The server SHOULD validate the client's permissions before establishing the SSE connection.
MUST use secure transport (HTTPS) to protect data integrity and confidentiality.
Implement rate limiting on the server to prevent abuse of the SSE endpoint.
The client SHOULD listen for error events and handle them appropriately, such as by retrying the connection or displaying an error message to the user.
The client SHOULD check for the X-SSE-Terminate header in the response and terminate the connection if it is present and set to true.
Example
OpenAPI Document Example
openapi: 3.1.0
info:
title: Server Side Events API
version: 1.0.0
paths:
/events:
get:
summary: Subscribe to server side events
operationId: subscribeEvents
responses:
'200':
description: Stream of server side events
content:
text/event-stream:
schema:
type: string
examples:
- |
event: message
data: {"message": "Hello, World!"}
id: 1
event: update
data: {"update": "New data available"}