Streaming APIs

Streaming APIsApplication Programming Interface. Refers to a set of functions, procedures, protocols, and tools that enable users to build application software. allow customers to subscribe to a select set of services instead of polling the NB API to get an aggregated state or statistics of the events. For example, with streaming APIs, the customers can get notifications about the following types of events:

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

For a complete list of supported services, see the next section. With streaming API, the customers can write value-added applications based on the aggregated context.

Supported Services

The streaming API supports the following services, for a definition of each of the services, see the next section.

• Location
• Security
• AppRF
• Audit
• Monitoring

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	API	Description
   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 or Unsubscribing a Streaming API Topic

To receive streaming events from a topic, first subscribe to the topic in Aruba Central.

To subscribe to a streaming API topic:

1. Log in to Account Home.
2. Under Global Settings, click the Webhooks menu option.
3. Click the Streaming tab.
4. In the Streaming APIs tab, select the check box corresponding to the topic that you want to subscribe.

   To unsubscribe a topic, clear the corresponding check box. The following topics are available for download:

   • Location—The location messages publish the location of associated clients or rogues and these are published every 50 messages or 10 seconds apart.
   • Security—When a new rogue is detected or a suspect is promoted to rogue, a rogue event is published to the streaming server.
   • AppRF—AppRF stream is the flow of all the client sessions which is intra-internet bound happening in the network.
   • Audit—The Audit messages are sent to notify events like device connectivity, configuration status, and firmware status.
   • Monitoring—Monitoring publishes the messages about statistics and states of monitoring data.

Downloading Protobuf Definition for a Streaming API topic

To download the protobuf definition, complete the following steps:

1. Log in to Account Home.
2. Under Global Settings, click the Webhooks menu option.
3. Click the Streaming tab.
4. In the Streaming APIs table, click the Download button corresponding to the protobuf definition for the topic to which you have subscribed.

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:

Enabling Data Streaming From a Topic

Use the WebSocket endpoint and access token to establish a WebSocket connection and start streaming data for the topics to which you have enabled subscription. Create a WebSocket connection to enable API streaming from Aruba Central.

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:

   Header	Description
   UserName	Username of the admin. This is an optional header.
   Authorization	Access token. For more information about how to generate the key, see Subscribing or Unsubscribing a Streaming API Topic.
   Topic	Value of the topic to which you have subscribed. The value should be one of the following: Location Security AppRF Audit Monitoring

3. Start the read loop to read the events. The payload is a protocol buffer message.

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 CentralUI, 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:
   • API—https://<central-host>/streaming/token/validate
   • Method—GETGET refers HTTP request method or an SNMP operation method. The GET HTTP request method submits data to be processed to a specified resource. The GET SNMP operation method obtains information from the Management Information Base (MIB).
   • Authorization—Enter the current token

   The API will return the same token if the old token is not expired or will return a new token in case the old token is expired.