Platform API Reference

The Platform API is responsible for recording telemetry data and performing device-to-device messaging. Although this page describes the pure REST API for platform operations the recommended way to reach the Platform API is though client libraries that are currently available for .NET-based devices and devices running Linux (Raspberry Pi, etc.).

The API is versioned and uses custom authentication headers.

It’s important to mention that there are two interfaces where the platform services can be reached:

The Platform API is for devices that mostly record telemetry data and/or send message to other devices quite rarely (eg. every minute once or more infrequently) and does not receive messages too frequently and doesn’t require incoming messages to arrive ASAP. So this API is for devices that are measuring something, controlling other devices however are not controlled too often or with low latency. The Platform Websocket interface is for devices that need to respond to control message is short period of time.

In the following description you will see some placeholders:

  • <APIURL>: the full url root of the API. Like api.thriot.io/platform
  • <DEVICEID>: 32 characters long unique identifier for device
  • <APIKEY>: 32 characters long crypto-safe random key

Telemetry data services

Record telemetry data
Description Record telemetry data that was measured by the device.
Url
<APIURL>/v1/telemetry
Verb POST
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Request object An object in JSON format that has maximum length of 1024 bytes.
Response object none
HTTP Response code 204 (No content)
Error codes 400 (Bad request): input parameter or validation error
401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Messaging

Send message to a device
Description Send message to a device. If the function successfully completes then the message is sent to the device. It doesn’t mean that the target device will successfully receive it. See subsequent operations for details.
Url
<APIURL>/v1/messages/sendto/<DEVICEID>
Verb POST
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service. The auth header always represents the caller not the message target.

Request object A string that has maximum length of 512 bytes.
Response object none
HTTP Response code 204 (No content)
Error codes 400 (Bad request): input parameter or validation error
401 (Unauthorized): bad authentication parameters passed
403 (Forbidden): No permission to send message to the device (they are not in the same network)
503 (Temporary unavailable): Call throttled or failed to send message

 

Receive and forget message
Description Receives and forgets a message. This completes a QoS 0-like reliability level from the receiver side (at most once). It means that in case of error the message cannot be rereceived.
Url
<APIURL>/v1/messages/forget
Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Request object none
Response object
{
 "Payload": "<MESSAGECONTENT>",
 "Timestamp": <INT64>,
 "SenderDeviceId": <DEVICEID>,
 "MessageId": <INT32>
}

or

null

If there is a message to be received then the Payload field will contain the message, the Timestamp will have the sending UNIX timestamp (seconds since 1970.1.1), MessageId is the unique, incremental message id sent to the device. If there is no message it operations returns a null.

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Peek message
Description Receives a message but doesn’t delete it. This completes a QoS 1-like reliability level from the receiver side (at least once). It means that in case of error the message can be rereceived. Works together with the commit operation. After each successful peek call (HTTP 200 + not null message content) a commit call should be issued. The client side should check if the message with the given MessageId has been already processed to go beyond QoS 1.
Url
<APIURL>/v1/messages/peek
Verb GET
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Request object none
Response object
{
 "Payload": "<MESSAGECONTENT>",
 "Timestamp": <INT64>,
 "SenderDeviceId": <DEVICEID>,
 "MessageId": <INT32>
}

or

null

If there is a message to be received then the Payload field will contain the message, the Timestamp will have the sending UNIX timestamp (seconds since 1970.1.1), MessageId is the unique, incremental message id sent to the device. If there is no message it operations returns a null.

HTTP Response code 200 (Ok)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Commit message
Description The commit call deletes the message that was previously received by the peek operation. Works together with the peek operation. After every peek call a commit call should be issued.
Url
<APIURL>/v1/messages/commit
Verb POST
Auth header
X-DeviceId: <DEVICEID>
X-ApiKey: <APIKEY>

The ApiKey can be the device key of the device, the network key of any of the container networks, or the api key of the container service.

Request object none
Response object none
HTTP Response code 204 (No content)
Error codes 401 (Unauthorized): bad authentication parameters passed
503 (Temporary unavailable): Call throttled

 

Advertisements