Websocket API¶

ELEMENT provides Websocket (RFC 6455) endpoints for receiving data in real-time. New data will be pushed to the websocket when available.

The communication is from server to client only. There are no commands from client to server.

Authentication¶

A valid API-Key is required to use the websockets. Permissions from API-Key will be applied.

Keep-Alive¶

A websocket connection is closed after 60 seconds of inactivity, if no Ping frame is send by the client.

If the client does not support the RFC standardized ping/pong procedure, the message "ping" can be used, which will trigger a "pong" reply from the server.

Sockets¶

The available Sockets are using the common REST url schema.

Device¶

For a device there are sockets for new packets and readings.

wss://element-iot.com/api/v1/devices/:device_id/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea
wss://element-iot.com/api/v1/devices/:device_id/readings/socket?auth=46cb688e2c0b468e26e914235d4b73ea

Tag¶

For a tag there are sockets for new packets and readings.

wss://element-iot.com/api/v1/tags/:tag_id/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea
wss://element-iot.com/api/v1/tags/:tag_id/readings/socket?auth=46cb688e2c0b468e26e914235d4b73ea

Stream¶

For a stream there are sockets for new packets and readings.

This is the recommended way for receiving data for multiple devices and tags.

wss://element-iot.com/api/v1/streams/:stream_id/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea
wss://element-iot.com/api/v1/streams/:stream_id/readings/socket?auth=46cb688e2c0b468e26e914235d4b73ea

Mandate¶

For a whole mandate there are sockets for packets and readings. The only allowed API-Key permissions are read_only and admin, no group permissions can be applied.

wss://element-iot.com/api/v1/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea
wss://element-iot.com/api/v1/readings/socket?auth=46cb688e2c0b468e26e914235d4b73ea

Replay of old events¶

In case you don't want to miss events when your application had a downtime, you can pass the after query parameter with the date of your last received reading or packet.

If an after parameter is found, the WebSocket will first replay all packets or readings since that date in the order earliest to latest, and then send live events.

Example:

wss://element-iot.com/api/v1/tags/:tag_id/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea&after=2020-02-05T12:30:21Z

Keep in mind that some datetime strings might contain special characters that need to be URL-Encoded.

Preload additional data¶

To load and receive additional data associated with the event, the optional query parameter preload can be used.

Packets¶

For packets, the preloads device, device.fields and device.interfaces can be used. device.fields and device.interfaces automatically preload device.

Example:

wss://element-iot.com/api/v1/tags/:tag_id/packets/socket?auth=46cb688e2c0b468e26e914235d4b73ea&&preload=device.interfaces,device.fields

Readings¶

Readings can utilize all preloads used by packets. Additionally, packet and packet.interface can be used. packet.interface will also preload packet.

Example:

wss://element-iot.com/api/v1/devices/:device_id/readings/socket?auth=46cb688e2c0b468e26e914235d4b73ea&preload=device,packet.interface