Central

The Central Developer Hub

Welcome to the Central developer hub. You'll find guides and documentation to help you start working with Central APIs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started with Streaming API

Streaming API is primarily used to read data from Aruba Central. Once a topic is subscribed by a client, the data is sent from Aruba Central in continuous streams based on subscribe-publish model.

Aruba Central uses protobuf format for streaming data. Protocol buffers are a flexible, efficient, automated mechanism for serializing structured data. It is faster and efficient to transport compared to other data formats such as XML.

Streaming API workflow is as follows,
1) WebSocket client subscribes to a topic and establishes secure connection to Aruba Central.
2) The data is serialized by using the proto file by Aruba Central Streaming service.
3) WebSocket client received the serialized protobuf data.
4) WebSocket client uses the same proto file used by Aruba Central and deserializes the data into human readable format.

Note

It is disabled by default but can be enabled for customers based on request.

Enable Streaming Topic

Streaming API can be accessed in Aruba Central from Account Home -> Webhooks -> Streaming. Streaming APIs table is available in Streaming page. By selecting the subscribe checkbox next to the Topic, Websocket clients will be able to subscribe to the respective Topic.

Establishing WebSocket Connection

In order to establish a secure WebSocket connection, Endpoint URL, Secure Websocket(WSS) Key and subscription topic name is required. They can be obtained from Account Home -> Webhooks -> Streaming page as shown in the image below.

API Endpoint URL: "wss://<central-host>/streaming/api"
Request Headers: UserName: <central-user-email>; Authorization: <wss-key>; Topic: <one-topic-from-available-topics>

Retrieve/Validate WebSocket Key

The WSS key refreshes every 7 days within Aruba Central. A REST API endpoint is available to retrieve/validate the WSS key. The API request to this endpoint accepts a key and returns the valid key. The returned key might be same as the user's key if its valid, otherwise most recent and valid key will be returned.

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

{
   "token": "xxxx"
}

Please Note

The streaming/token/validate API endpoint only retrieves/validates the WSS Key and does not generate a new WSS key.

Streaming API in Aruba Central WebUI

Streaming API in Aruba Central WebUI

Proto Files

Streaming API in Aruba Central sends data is ProtoBuf format. The .proto definitions can be downloaded by clicking the Download button as shown in the above image. The proto file downloaded from the link Streaming Protobuf Definition will be used to deserialize metadata. The proto files in the Streaming APIs table will be used to deserialize streaming data for the respective topic.

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 pick 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 as shown in the above image. This message contains data for the streaming topic along with some metadata such as Timestamp, Topic, Customer ID. Once the deserialization is done, the data field of the message will still be in protobuf format.

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

b. Streaming Topic data: The 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 as mentioned above. In this example, the deserialized data streamed from 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
  }
}

Updated about a month ago



Getting Started with Streaming API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.