Direct HTTP Connector

The HTTP IoT connector service is designed to facilitate communication between IoT enabled devices and web servers using the HTTP (Hypertext Transfer Protocol) protocol.
It acts as a bridge between IoT devices, which typically generate data or perform actions in the physical world, and cloud-based applications, where the data can be processed, analyzed, and transformed into valuable information.
In order to use this connector you have to enable and configure the HTTP Connector plugin.

Servitly HTTP Endpoints

According to which environment type and cloud provider, you should use the correct HTTP endpoint.

AWS

AZURE

Sending IoT Data

To send IoT data, the remote product or the IoT Platform must perform a POST to the following HTTP endpoint:

POST https://<BASE_URL>/data?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>
{
 "ts": 1689064634000,
 "data": {
   "foo": "bar",
   "baz": 123
 }
} 

Where placeholders are:

• BASE_URL: the HTTP connector base URL according to the target environment.

• MAPPING_ASSET_ID: the Asset ID that has been specified in the mapping panel for a thing

• MAPPING_ASSET_PATH: the message path, which is the concatenation of the path specified in the thing's mapping panel, and the path specified in the metric mapping panel

  <THING_MAPPING_PATH>/<METRIC_MAPPING_PATH> 

• AUTHORIZATION: the basic authorization header that uses the username and password specified on the thing, location, customer, or inherited from the tenant's default connector.

Into the data node, you can use any string key you prefer, but it is important that these keys will match the name specified in the metric mapping panel.
In this way, Servitly can extract the n-th field value and store it under the right metric.

Data field values can be strings, numbers, or boolean encoded by using the standard JSON data encoding.
For more details about how to encode values into the JSON payload refer to the Encoding Values article.

Sending multiple IoT data in a single request

Optionally, you can also send multiple messages in the same request, this can be done by adding an array in the payload.

POST https://<BASE_URL>/data?assetId=test-123&path=data
Authorization Basic <AUTHORIZATION>
[
 {"ts": 1689064634000, "data": {"temperature": 25.5}},
 {"ts": 1689066434000, "data": {"temperature": 25.3}},
 {"ts": 1689068234000, "data": {"temperature": 25.3}}
] 

Instead of using JSON format, the HTTP connector also supports sending data in CSV format.

POST https://<BASE_URL>/data?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>
timestamp,foo,baz
1689064634000,bar,123
1689065756000,xyz,456 

This can help reduce the number of bytes sent in the case of a mobile connection.

GZIP Request Compression

Optionally, to reduce the network traffic, you can send requests by using the GZIP compression. It is enough to add the following header to the request, and compress the payload according to the GZIP protocol.

Content-Encoding: application/gzip

Note that to have an advantage in using GZIP compression, at least 5 measures must be added in the payload.

Creating Work Sessions

The manual work session creation can also be triggered by the HTTP connector. In cases where the machine has a limited connection (e.g. GSM), it is possible to take advantage of this function to create a work session to be saved directly to the work session history along with the relative measure data, all in one API call.

POST https://<BASE_URL>/data/workSessions?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>

payload
{
 "name": "DRILLING",
 "title": "Pile 001",
 "description": "Location 1234345, depth: -220m",
 "csvHeaderRow": 6
}

file
10101010101

The request must be a MULTIPART request containing:

• payload: the JSON document providing the information of the Work Session being created. This includes, the name of the Work Session Definition along the title and description of the Work Session instance.
  Optionally you can provide the csvHeaderRow, which represents the CSV row index (1-based) where the dataset header is present (e.g. timestamp,foo,baz).

• file: the CSV file containing all the measure data related to the Work Session.
  This file can also be a ZIP file containing a single CSV file.

How to send remote updates

HTTP connector communication can also be bidirectional, as long as the platform you're using exposes APIs to be invoked to send updates to remote products.
In the HTTP Connector plugin you can configure the method, URL endpoint, request parameters and headers.

For any update made on the cloud side (command execution, configuration parameter update, firmware update), the Servitly standard JSON message is forwarded to the external endpoint as-is with in addition the topic field providing the update target (e.g. <THING_ASSET_ID>/<COMMAND_PATH>).

{
 "topic": "lamp-123/change-status",
 "data": {
   "powerOn": true
 }
}

Any payload transformation will have to be handled by the external system, or by interposing an AWS Lamda or Azure function callable via HTTP.

Request Rate Limits

The HTTP connector endpoint can be invoked by using the same rate limit as the publishing rate limit of the thing. Connected products can publish data with a limited rate, for more details refer to the Publishing Rate Limit article.

For instance, given a limit of 3600 measures/hour at the single thing level, you have a total of 3600 API requests/hour that can be performed.

The rate limiter uses a refill policy allowing you to perform 60 request / minute, with an overdraft of 120 request for a few minutes.

In case you get the 429 response, you can inspect the "Retry-After" header to know how much time you have to wait before the next request.

Be careful, that if you include multiple messages in the same request, each message consumes a request.