Streaming API

Streaming API Application Programming Interface. Refers to a set of functions, procedures, protocols, and tools that enable users to build application software. allows customers to subscribe to select set of services instead of polling the NB API Northbound Application Programming Interface. A northbound interface is an application programming interface (API) or protocol that allows a lower-level network component to communicate with a higher-level or more central component. to get an aggregated state or statistics of the events. For example, with Streaming API, the customers can get notifications about the following types of events:

  • The UP and DOWN status of the devices
  • Change in location of stations

For a complete list of supported services, with Streaming API, users can write value-added applications based on the aggregated context.

Supported Services

Streaming API supports the following services:

Viewing the Streaming API Page

Perform the following steps to view the Streaming API page:

  1. In the Aruba Central app, set the filter to Global.

  2. Under Maintain, click Organization > Platform Integration > Streaming API.

    The following is an illustration of the Streaming API page:

    Figure 1  View of the Streaming API Page

    The parameters in the page are described in the following table. Refer to the callout numbers.

    Table 1: Parameters of the Streaming API Page

    Callout

    APIDescription

    1

    Topic

    A list of available topics for streaming APIs. To receive streaming events from a topic, subscribe to the specific topic.

    2

    Subscribe

    Enables Aruba Central to stream events for a specific topic when this box is enabled.

    3

    Protobuf Definition

    Definition of the specific topic. All WebSocket response messages are encapsulated in a protocol buffer, the format of which you can download.

    4

    Key

    Access token for establishing a WebSocket connection.

    5

    Endpoint

    WebSocket endpoint address for the Aruba Central instance.

    6

    Streaming Protobuf Definition

    The protocol buffer in which all the incoming streaming messages are encapsulated. This protobuf is further used to identify the topic of the message received and decode the topic-specific protobuf message.

Subscribing to a Streaming API Topic

  • Only users with Aruba Central Administrator role can subscribe to, or unsubscribe from, a topic. For more information, see the Assignments section in the HPE GreenLake Edge to Cloud Platform User Guide.
  • In case a live WebSocket connection breaks, reconnect the connection.

To subscribe to a streaming API topic:

  1. In the Aruba Central app, set the filter to Global.
  2. Under Maintain, click Organization > Platform Integration > Streaming API.
  3. In the Streaming APIs table, select the check box corresponding to the topic that you want to subscribe. To unsubscribe a topic, clear the corresponding check box.
  4. In the Streaming page, the following details are displayed:
    • Key—Access token. The token comes with a validity of seven days after which a new token needs to be generated.
    • Endpoint—WebSocket endpoint.
    • Streaming Protobuf Definition—Allows you to download the Streaming protocol buffer definition.

Use the WebSocket endpoint and access token to establish a WebSocket connection and start streaming data for the topics you have subscribed to.

Downloading Protobuf Definition for a Streaming API topic

To download the protobuf definition, complete the following steps:

  1. In the Streaming APIs table, click the Download button corresponding to the protobuf definition for the topic to which you have subscribed. The following topics are available for download:
    • Apprf—Protocol buffer specification of the AppRF topic.
    • Audit—Protocol buffer specification of the Audit topic.
    • Monitoring—Protocol buffer specification of the Monitoring topic.
    • Presence—Protocol buffer specification of the Presence topic.
    • Location—Protocol buffer specification of the Location topic.
    • Security—Protocol buffer specification of the Security topic.

Retrieving a New Token

The access token comes with a validity of seven days after which a new token needs to be generated.

You can retrieve the token either directly from the UI or by using the API.

  1. To retrieve the new access token from the Aruba Central UI, complete the following steps:
    1. In the Aruba Central app, under Maintain, click Organization > Platform Integration > Streaming API tab.
      The Streaming page is displayed.
    2. You can retrieve the valid token from the Key field. The token gets refreshed automatically after seven days of its generation.
  2. To retrieve the new access token from the API, here are the details required:

Enabling Data Streaming From a Topic

Complete the following steps to receive streaming events from Aruba Central:

  1. Create a WebSocket connection: wss://<central-host>/streaming/api
  2. Set the following additional headers:
    • UserName—Username of the admin. This is an optional header.
    • Authorization—Access token. For more information about how to generate the key, see Subscribing to a Streaming API Topic.
    • Topic—Value of the topic to which you have subscribed. The value should be one of the following:
      • apprf
      • monitoring
      • audit
      • presence
      • location
      • security
  1. Start the read loop to read the events. The payload is a protocol buffer message.

Decoding WebSocket Response Messages

All WebSocket response messages are encapsulated in a protocol buffer. When a message is received, use the subject (topic) to identify the message and invoke an appropriate message processor. To decode the message, refer to the protocol buffer specification of the respective topic.

The format is as follows:

message MsgProto { string subject = 2; // subject bytes data = 3; // payload int64 timestamp = 4; // received timestamp string customer_id = 5; // customer id to which this data belongs string msp_id = 6; // optional field indicating the msp_id }