HTTP Device API Reference

Getting started

HTTP basics

HTTP is a general-purpose network protocol that can be used in IoT applications. You can find more information about HTTP here. The HTTP protocol is TCP-based and uses a request-response model.

Client libraries setup

You can find HTTP client libraries for different programming languages on the web. Examples in this article will be based on curl. In order to set up this tool, you can use instructions in our Hello World guide.

HTTP Authentication and error codes

IIoTNext supports only the secure version of HTTP protocol: HTTPS, where communication is fully encrypted. We will use access token device credentials in this article and they will be referred to later as $ACCESS_TOKEN. The application needs to include $ACCESS_TOKEN as a path parameter in each HTTP request. Possible error codes and their reasons:

400 Bad Request – Invalid URL, request parameters or body.
401 Unauthorized – Invalid $ACCESS_TOKEN.
404 Not Found – Resource not found.

Key-value format

By default, IIoTNext Platform supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long or JSON. For example:

{
   "booleanKey" : true,
   "stringKey" : "value1",
   "jsonKey" : {
      "someNumber" : 42,
      "someNestedObject" : {
         "key" : "value"
      },
      "someArray" : [
         1,
         2,
         3
      ]
   },
   "doubleKey" : 42,
   "longKey" : 73
}

Telemetry upload API

To publish telemetry data to IIoTNext Platform, send a POST request to the following URL:

https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/telemetry

The simplest supported data formats are:

{"key1":"value1", "key2":"value2"}

[{"key1":"value1"}, {"key2":"value2"}]

Please note that in this case, the server-side timestamp will be assigned to uploaded data!

In case your device is able to get the client-side timestamp, you can use the following format:

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’

Example using curl in the command line:

# for IIoTNext cloud Platform

# Publish data as an object without timestamp (server-side timestamp will be used)
curl -v -X POST --data "{"temperature":42,"humidity":73}" https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

Attributes API

IIoTNext Platform attributes API allows devices to

Upload client-side device attributes to the server.
Request client-side and shared device attributes from the server.
Subscribe to shared device attributes from the server.

Publish attribute update to the server

In order to publish client-side device attributes to IIoTNext Platform, send a POST request to the following URL:

https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes

new-attributes-values.json:

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Example commands:

# for IIoTNext Platform Cloud

# Publish client-side attributes update
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# Publish client-side attributes update from file
curl -v -X POST -d @new-attributes-values.json https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

Request attribute values from the server

In order to request client-side or shared device attributes to IIoTNext Platform, send a GET request to the following URL:

https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Example:

# for IIoTNext Cloud Platform

# Send HTTP attributes request
curl -v -X GET "https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

Result:

{"key1":"value1"}

Please note, the intersection of client-side and shared device attribute keys is a bad practice! However, it is still possible to have the same keys for client, shared, or even server-side attributes.

In order to subscribe to shared device attribute changes, send GET request with optional “timeout” request parameter to the following URL:

https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes/updates

Once shared, the attribute will be changed by one of the server-side components (REST API or Rule Chain) the client will receive the following update:

Example:

# for IIoTNext Cloud Platform

# Send HTTP attributes request
curl -v -X GET https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Result:

{"key1":"value1"}

JSON value support

Supporting JSON data structures in telemetry and attributes API helps to simplify work with device configuration. JSON support allows you to upload from the device and push to device nested objects. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when IIoTNext Platform stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

RPC API

Server-side RPC

In order to subscribe to RPC commands from the server, send GET request with optional “timeout” request parameter to the following URL:

https://host:port/api/v1/$ACCESS_TOKEN/rpc

Once subscribed, a client may receive rpc request or a timeout message if there are no requests to a particular device. An example of RPC request body is shown below:

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

where

id – requestid, the integer request identifier
method – RPC method name, string
params – RPC method params, custom JSON object

and can reply to them using a POST request to the following URL:

https://host:port/api/v1/$ACCESS_TOKEN/rpc/{$id}

where $id is an integer request identifier.

Example subscribe:

# for IIoTNext Cloud Platform

# Send HTTP attributes request
curl -v -X GET https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

Example Reply:

curl -v -X POST -d @rpc-response.json https://app.iiotnext.com/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"

Reply Body:

{"result":"ok"}

HTTP Device API

IIoTNext Platform