WebSocket
Websockets provides a live stream of data from devices or collections directly through the API. The endpoint is dynamically built based on the collectionId as well as the deviceId if you’re only looking to subscribe to messages from a single device.
Connecting to a WebSocket
With API token
To be able to connect you first need an API Token which can be created in the Span dashboard. The token must be a read-only token due to security and have access to the collection or the device in question. To use the WebSocket endpoint, authenticate with the header X-API-Token and set the value to be your API-token.
X-API-Token: abcdef...hijkg
With query parameter
Some websocket libraries does not support custom headers on the request, particularly if you are using a browser. This is not a recommended way to do the request since it exposes the API token to any proxies between you and the API but it may come in handy in a pinch. Add the parameter ?api_token={token} to the request to use this.
The API token must be a read-only token. A token with write access is rejected by the API.
With login token
You may omit the API token if you have a JWT token from the regular login process. Send the following JSON structure after connecting to authenticate with the service:
{
"jwt": "{ your JWT token }",
"collectionId": "{ collection ID as set in the URL}",
"deviceId": "{optional device ID to filter on device. Leave blank for all devices}"
}
Endpoint
Each collection has a websocket in the from resource. Replace {collectionId} with your collection ID and use the following URL:
wss://api.lab5e.com/span/collections/{collectionId}/from
Word of warning
A websocket isn’t suited for production systems, only for testing and demonstration purposes. Use either webhooks or MQTT if you want message buffering.