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
)