Server-Sent Events are asynchronous messages sent by Prime Infrastructure to notify consumers of a set of key events. Prime Infrastructure uses the W3C Server-Sent Events technology to send notification messages to consumers.
Prime Infrastructure sends several types of events. Each event has its own type. You may subscribe to all of them or only those that you want to receive.
Event | Description |
---|---|
event | An event data message that is sent when an entity is created, updated, or deleted. Contains at least one event. See
Response Format section for details.
|
error | An event indicating that an error occurred while processing events. Will contain descriptive error message.
event: error data: <streamError message="Active virtual domain has been removed. The connection will be closed, try to reconnect." /> |
ping | A service event that is sent to check if the client is still alive. Prime Infrastructure sends them every 30 seconds. The event message contain no data and will be ignored by an SSE client.
event: ping : ping |
greeting | A service event that is sent immediately after the client has been connected. The event message contain no data and will be ignored by a SSE client.
event: greeting : Successfully subscribed to Alarms events |
URL Pattern | Request-Type | Function |
---|---|---|
/api/v4/sse | GET | Get all event types. |
/api/v4/sse/{eType} | GET | Subscribe to events of {eType} entity, for example Alarms. |
/api/v4/sse/{eType}/{aType} | GET | Subscribe to events of {eType} entity of {aType} event type, for example Alarms/CREATED. |
Query Parameter | Meaning |
---|---|
.json | When present, indicates that the response should be returned in json format. Can be used when your SSE client does not support sending additional HTTP headers. |
.xml | When present, indicates that the response should be returned in xml format. This is the default behavior in the absence of the .json parameter. Can be used when your SSE client does not support sending additional HTTP headers. |
_docs | Displays the documentation page. |
_ctx.domain | Sets the active domain to be that named in the query parameter value - this is, by default, "sticky" in the sense that once set, the active-domain remains set. The "stickiness" is not RESTful, and so it can be switched off in configuration. |
HTTP Header | Value | Meaning |
---|---|---|
Accept | text/xml or application/json | May be used to control whether the event returned is formatted as XML or JSON. |
Accept-Language | For example: en-US | Specifies the language to be used in the response. This may affect error messages that may be returned. |
Accept-Encoding | gzip | Specifies that compressed data may be returned to the client. |
Content-Encoding | gzip | Specifies that data supplied by the client with a request is compressed. |
An SSE event stream is delivered as a streaming HTTP response. The server responds with a custom "text/event-stream" content-type, and then streams the UTF-8 encoded event data. Event data format can be either xml or json depending on the requested format.
Entity event data is returned in an 'envelope' that has this structure:
<?xml version="1.0" encoding="utf-8"?>
<streamResponse type="Alarms" rootUrl="https://my_server/webacs/api/v4/sse"
requestUrl="https://my_server/webacs/api/v4/sse/Alarms"
responseType="listEvents">
...
</streamResponse>
The structure consists of:
The top-level element in the response document, with the following attributes:
Depending on the value of the /streamResponse/@responseType attribute the elements that form the contents of the <streamResponse> will be as follows:
/streamResponse/entityType
/streamResponse/streamEvent* - Each element contains the structured data that describes an entity event.
Errors that occur while establishing SSE connection are reported in a canonical error document in the same format as used for /op and /data requests. Errors that occur after the SSE connection is established are reported as a SSE messages with error data type.
Depending on the severity of the error the connection may be persisted or closed. We explicitly close connections in following cases:
You will get an error message indicating that an error occurred before the connection is closed.
event: error data: <streamError message="Active virtual domain has been removed. The connection will be closed, try to reconnect."/>
The document structure is as follows: