Getting Started with Streaming API

Streaming API is primarily used to subscribe and receive real-time data from Aruba Central. It follows the publish-subscribe model in which any message published to a topic is immediately received by all subscribers to the topic. Applications of Streaming API include event-driven architecture and real-time monitoring.

Aruba Central uses Secure WebSocket (WSS) protocol for Streaming API. The publisher is the Aruba Central (WebSocket Server) and the subscriber is the WebSocket client application implemented by the end user.

Some use-cases are building a device statistics monitoring dashboard, device state monitoring application, monitor client location and history, detect the presence of the unassociated clients and more.

Enable Streaming Topic(s)

Streaming API can be accessed in Aruba Central from Account Home -> Webhooks -> Streaming. Streaming APIs table is available in the Streaming page. Selecting the subscribe checkbox next to the Topic will allow the subscribers to subscribe to the enabled topic(s).

📘

Note

Streaming APIs in Aruba Central is only supported for devices with advanced licenses.

Establish WSS connection and Subscribe to a Topic

WebSocket protocol is designed over HTTP and uses HTTP during the initial handshake. The following are the details required to establish a Secure WebSocket Connection

Server URL: "wss://< base-url >/streaming/api"
HTTP Request Headers: UserName: <central-user-email>; Authorization: <wss-key>; Topic: <one-topic-from-available-topics>

All the required information can be obtained from Global -> Organization -> Platform Integration -> Streaming page as shown in the image below.

• Server URL: This is the WebSocket Server URL in the format "wss://[central_server_base_url]/api" and can be obtained from Endpoint section of the Streaming API page.
• Aruba Central Username: [Optional] Provide an Aruba Central User's email address.
• WSS Key: Key copied from the Streaming API page.
• Streaming Topic: Only one topic per WSS connection is supported. Choose from the topics shown in Streaming API page. (security, location, monitoring, audit, apprf and presence)

📘

Streaming Key & Topics

The WSS Key is applicable to all selected topics. There is no individual key for each topic.

Secure WebSocket Key

The WSS key can be obtained from the Streaming API page (as shown in the picture). The WSS Key is a JSON Web Token (JWT) using HS256 algorithm. WSS Key is valid for seven days from the time it was created. The WSS key created timestamp can be obtained by decoding the key using JWT decoder. (More info on the JWT decoder can be found in jwt.io)

The sample of the decoded key is as follows, (The Created timestamp is in epoch time)

{
  "customer_id": "xxxxxxxxxxxxxxxxxxx",
  "Created": 1625004851
}

Retrieve/Validate WebSocket Key

Upon reaching the seven days time from the Created timestamp, the WSS key is automatically refreshed by the Aruba Central. The old key will continue working for the active connections. For new connections, the new WSS Key is required.

🚧

Please Note

The WSS Key cannot be refreshed by the end user. The Aruba Central automatically refreshes them every 7 days.

One can obtain the new WSS key by getting back to the Streaming API page but it can also be obtained via an API call. The API request to this endpoint accepts a WSS key. The successful API response will have one of the two cases.

• The returned key will same as the key provided in the API request if it is valid (not expired),
• Otherwise, the valid key (new key) will be returned.

HTTP/API Request Details

API Endpoint URL: https://< base-url >/streaming/token/validate
Request Method: GET
Request Header: "Authorization" : "< wss-key >"
Response Data:

{
   "token": "xxxx"
}

The is obtained from the Streaming API page as shown in the picture above.

Processing the streaming API data

Aruba Central uses the Protocol Buffers for the data transferred in streaming API. Protocol buffers are a flexible, efficient and automated mechanism for serializing structured data. It is faster and efficient to transport over the network compared to other data formats such as XML/JSON.

Proto Files

The structure or format of the data is described in the .proto file in the protocol buffer language. Data from the Aruba Central (publisher) was serialized using this .proto file. Thus the same file should be used to de-serialize the data by the WSS client (subscriber).

Each file consists of multiple messages. The smaller messages can be nested to form larger messages. Each message consists of message fields and they are of type required, optional and repeated.

• required field type consists of one message and will be available every time this message is received.
• optional field type consists of one message and is optional. It may or may not be available in every received message.
• repeated field type consists of multiple messages (a list of messages).

In Aruba Central Streaming API, there is a top level .proto file used as basis for every topic. It consists of the metadata and the actual data. The top level proto file can be downloaded from the streaming API page by click on the link Streaming Protobuf Definition. The actual data varies for every Topic. The .proto files are available for every streaming Topic. It can be downloaded by clicking the Download button next to every Topic as shown in the above image.

Before the .proto files can be used, it should be compiled based on the programming language used. For more information, refer the tutorial section of the protocol buffer documentation and select a programming language.

Deserialize streaming data

Follow the steps below to deserialize the protobuf data.

a. Metadata: The received protobuf message should be deserialized using compiled proto file obtained from Streaming Protobuf Definition. This message contains data for the streaming topic along with some metadata such as Timestamp, Topic, Customer ID.

{
  "subject": "monitoring",
  "data": "<serialized-protobuf-data>",
  "timestamp": 1599247013111420815,
  "customer_id": "<customer-id>"
}

b. Streaming Topic data: data field from the step above should be deserialized further based on the subscribed topic. Proto files for respective topic can be obtained from Protobuf Definition column in Streaming APIs table. This proto file has to be compiled based on the programming language used, as mentioned above. In this example, the deserialized data from the monitoring topic is shown below.

{
  "customer_id": "<customer-id>",
  "data_elements": STAT_DEVICE,
  "device_stats": {
    "device_id": "<device-serial>",
    "timestamp": 1599247200,
    "uptime": 12819331,
    "cpu_utilization": 3,
    "mem_total": 527089664,
    "mem_free": 321039552,
    "mem_utilization": 39
  }
}

Streaming API caveats

• Only one topic per WSS connection is supported. To stream multiple topics, create multiple WSS connections.
• Number of WSS connections per streaming Topic is limited to five WSS connections .
• The WSS key can't be refreshed by the end user. It is automatically refreshed by Aruba Central every seven days .
• The WSS Key is applicable to all selected topics. There is no individual key for each topic.