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:

• Audit—The Audit messages are sent to notify events like device connectivity, configuration status, and firmware status.
• AppRF—AppRF stream is the flow of all the client sessions. For each connected devices (IAP/BGW), It lists the client's web session information of the past 14/15 minutes (Ip, Rx/Tx, Timestamp, etc).
• Monitoring—The monitoring streaming event is generated for state message (on state change) and stats message (received for every 5 minutes).
• Presence —The Presence events are sent to provide details of all associated and unassociated clients detected by Instant AP devices.
• Location—A location event is generated when the location of a client is computed using RSSI Received Signal Strength Indicator. RSSI is a mechanism by which RF energy is measured by the circuitry on a wireless NIC (0-255). The RSSI is not standard across vendors. Each vendor determines its own RSSI scale/values. values reported by IAPs. The event message includes co-ordinates of the client on the VisualRF floorplan.
• Security—The Security streaming event is generated when the IAPs have enabled Intrusion Detection. This feed contains all the IDS Intrusion Detection System. IDS monitors a network or systems for malicious activity or policy violations and reports its findings to the management system deployed in the network. detections reported by the IAPs in the network.

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	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 to a Streaming API Topic

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:
   • API— https://<central-host>/streaming/token/validate
   • Method—GET GET 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.

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

3. 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: