Open Server-Sent Events Stream
Open Server-Sent Events Stream is not a WSAPI operation in the standard sense, but rather the URI used by an SSE client to open a stream previously created by the Create Server-Sent Events Stream operation. The stream identifier is passed as a query parameter to the URI.
HTTP method and URI
GET /api/sessions/operations/open-server-sent-events-stream
Query parameters:
Name | Type | Rqd/Opt | Description |
---|---|---|---|
stream-id | String | Required | The configured stream identifier to subscribe the SSE client to, as returned from the Create Server-Sent Events Stream operation. |
initial-events | Boolean | Optional | A value of true causes an initial set of events to be sent on the stream for
everything registered for. A value of false causes only asynchronous notifications of changes
to be sent. The default is false. |
Response body contents
On successful completion, the response body will be as defined by the SSE specification. Events may then be emitted to the stream in the form described by Notification event formats.
Description
This operation opens a configured stream and registers a client to begin listening for events. Refer to Server-Sent Events (SSE) for more details.
On successful execution, response code 200 (OK) is returned with Content-Type "text/event-stream" and events may begin flowing. The passed stream-id must be a valid, configured identifier of a stream belonging to a fully authenticated session; otherwise, status code 404 (Not Found) is returned. If the identified stream is currently open, it is closed prior to being re-opened.
If initial events are requested, they will be processed and delivered asynchronously to this request with the special events of “initial-events-start” and “initial-events-end” before and after them, respectively. Initial events are guaranteed to be delivered prior to any change events, although any change events that occur during initial event processing will still be delivered once that completes.
Note also that the request of initial events will be remembered for the life of the stream being open. Therefore, if the stream’s configuration is updated while open to add additional registrations, a set of initial events will be sent for the added items. Additionally, if any object-related registrations are filtered by class or not filtered at all, new objects in the inventory will cause initial events for them.
Authorization Requirement
This operation has no authorization requirements.
The stream-id is the authorization token for the operation, created by a fully authenticated session with the Create Server-Sent Events Stream operation, ensuring the stream is only sent events the user is authorized to receive.
HTTP status and reason codes
On success, HTTP status code 200 (OK) is returned with Content-Type "text/event-stream".
The following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and an associated error message.
HTTP error status code | Reason code | Description |
---|---|---|
400 (Bad Request) | Various | Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes. |
404 (Not Found) | 7 | The stream-id does not designate a known stream for the session. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Usage notes
The intended use is to simply pass the URI with the stream-id as a query parameter to an SSE client’s event source implementation which is then opened, such as follows:
new EventSource(
https://myhmc:6794/api/sessions/operations/open-server-sent-events-stream?stream-id=mystreamid
)