Aruba Central Online Help

Streaming API

Streaming APIApplication 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 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.

  • Streaming API service in Aruba Central is enabled if one of the devices in the account has an Advanced License. If the account has only Foundation License, Steaming API tab is not displayed in Aruba Central. For more information about streaming API feature in the Aruba Central licensing model, see Aruba Central Licensing Guide.
  • Streaming API service is not supported at MSP level.

Supported Services

Streaming API supports the following services:

Viewing the Streaming API Page

Perform the following steps to view the Streaming API page:

  1. Log in to Account Home.
  2. Under Global Settings, click the Webhooks menu option.
  3. Click the Streaming tab.

    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 Aruba Central admin users can subscribe to, or unsubscribe from, a topic.
  • In case a live WebSocket connection breaks, reconnect the connection.

To subscribe to a streaming API topic:

  1. In the Account Home page, under Global Settings, click Webhooks. The Webhooks page is displayed.
  2. In the Webhooks page, click Streaming tab. The Streaming page is displayed.
  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 Webhooks > 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 Account Home page, under Global Settings, click Webhooks > Streaming 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 }