To connect to Central's Streaming API the client application must have compatibility for WSS connections. Whether this is through a browser or a package for your favorite coding language is up to you!

Connection Process

1. Generate an access token
2. Prepare WSS endpoint
   1. The base URL for connecting to the Streaming API is the following:

      wss://<central-base-url>/network-services/v1alpha1/<endpoint-path>
      

   2. Choose a Streaming Event and add it to the WSS endpoint. Example endpoint for streaming all Audit Trail Events

      wss://<host>/network-services/v1alpha1/audit-trail-events
      

   3. Choose and apply any additional event filters to the endpoint with the event-types query parameter. In this example the device monitoring filter is being applied. Reference the Events section for more details.

      wss://<host>/network-services/v1alpha1/audit-trail-events?event-types=com.hpe.greenlake.network-services.v1alpha1.audit-trail.device-monitoring
      

3. Initiate the connection

Disconnect Process

To disconnect cleanly from the Central API use your packages preferred close method. Disconnecting cleanly with a proper close frame is an important part of the process for both client and server. The close frame is seen by both the client and the server and provides the reason for the disconnect. Generally, for most languages this will take the from of a .close() method. If your package doesn't provide a default value for the close status code it's recommended to provide one, however it's common for defaults to be sent for most packages. The most common status code for a close is 1000 indicating a normal closure. This indicates the purpose for which the connection was established has been fulfilled.

Streaming API Queue

In the case of an unexpected disconnect, Central will store and queue events up to 15 minutes after the time of disconnect. On a reconnect the Streaming API will send all events that are queued which had been triggered since the disconnect. After this 15 minute window has expired without a reconnect the queue will clear. At this point the event data is lost and cannot be recovered.

Reconnection Process

Once a WebSocket to Central's Streaming API has connected it will remain open until the access token expires or the connection closes. Sometimes a WebSocket connection may be closed unexpectedly. This can be for a variety of reasons including network issues, server/client bugs, misconfigurations, or something else. In any case, best practice is to include reconnection logic into the client application.

In the case of an expired token the HPE Greenlake API can be used to generate a new access token programmatically to reconnect. With a new access token, update the Authorization header in the request with the new token. All other headers and query parameters should stay the same if the goal is to reconnect with no changes. A successful reconnection will trigger the queue to send all applicable events triggered within 15 minutes after the disconnect.

📘

Client Responsibility

Reconnection is the responsibility of the client application. The Streaming API does not initiate a reconnect.

Events

Understanding events is the key for connection management. Please review the Events section of our getting started guide for general information on Events. Filtering for specific event data falls under this category and is key to setting up streaming connections efficiently.

Event Filtering

Clients can filter which events they receive from a streaming endpoint using the event-types query parameter in the request when connecting. Valid event types for each endpoint can be found in their CloudEvents guide.

event-types: com.hpe.greenlake.network-services.v1alpha1.audit-trail.device-monitoring

Multiple event-types can be applied to the query parameter by providing a comma separated list of events.

event-types: com.hpe.greenlake.network-services.v1alpha1.audit-trail.device-monitoring,com.hpe.greenlake.network-services.v1alpha1.audit-trail.configuration

Receive all events (no filtering):

This example endpoint will receive all Audit Trail Events from the Streaming API .

wss://<host>/network-services/v1alpha1/audit-trail-events

Receive specific events only:

This example endpoint will only receive device-monitoring events from the Audit Trail endpoint. Event type filters can be found in the Supported Events sections of each endpoint's guide. Filtering event-types with supported events is applied the same way for each CloudEvent endpoint.

wss://<host>/network-services/v1alpha1/audit-trail-events?event-types=com.hpe.greenlake.network-services.v1alpha1.audit-trail.device-monitoring

🚧

Validation

Event types in the query parameter must match supported endpoint event types. Invalid event types result in 400 response code. Multiple event types can be specified as comma-separated values.

Connection Examples

Simple connection examples can be found in our other guides linked below.

• Postman provides a pre configured Streaming API collection that allows you to quickly connect to Central, subscribe to streaming events, and view live streaming events directly in the Postman UI without writing any code.
• PyCentral, our Python SDK, simplifies Streaming API usage by managing connections and automatically decoding streaming payloads, enabling you to build real time streaming applications with minimal setup and code.