REST Connector Configuration

Connector configuration: rest.json
Next steps

This guide will help you to get familiar with REST Connector configuration for ThingsBoard IoT Gateway.
Use general configuration guide to enable this Connector.
The purpose of this Connector is to create API endpoints and get data from received requests.
Connector is also able to push data to external HTTP(S) API based on the updates/commands from ThingsBoard.

This connector is useful when you have some HTTP(S) API endpoints in your device or some data in external resource and you would like to push this data to the ThingsBoard.

We will describe connector configuration file below.

Connector configuration: rest.json

Connector configuration is a JSON file that contains information about how to create API endpoints and how to process the data.
Let’s review the format of the configuration file using example below.

Example of REST Connector config file. Press to expand.

Example listed below will create a server on a localhost using 5000 port. Connector will use basic HTTP authorization using username and password. Then, connector will create endpoints from a list of endpoints using endpoints from mapping section. See more info in a description below.

{
  "host": "127.0.0.1",
  "port": "5000",
  "mapping":[
    {
      "endpoint": "/test_device",
      "HTTPMethod": [
        "POST"
      ],
      "security":
      {
        "type": "basic",
        "username": "user",
        "password": "passwd"
      },
      "converter": {
        "type": "json",
        "deviceNameExpression": "Device ${name}",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}",
            "converter": "CustomConverter"
          }
        ]
      }
    },
    {
      "endpoint": "/test",
      "HTTPMethod": [
        "GET",
        "POST"
      ],
      "security":
      {
        "type": "anonymous"
      },
      "converter": {
        "type": "custom",
        "class": "CustomConverter",
        "deviceNameExpression": "Device 2",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "Model2"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}"
          }
        ]
      }
    }
  ]
}

General section

Parameter	Default value	Description
host	http://127.0.0.1:5000	Domain address or ip of the server.
SSLVerify	true	Verify or no SSL certificate on the server if available.

Mapping section

This configuration section contains array of objects with endpoints that the gateway will create.
Also this section contains settings about processing incoming messages (converter).
After request receiving, the message from the request is analyzed to extract device name, type and data (attributes and/or timeseries values).
By default, the gateway uses Json converter, but it is possible to provide custom converter.

Note: You can specify multiple mapping objects inside the array.

Parameter	Default value	Description
endpoint	/test_device	Url address of the endpoint.
HTTPMethod	GET	HTTP method allowed for endpoint (GET, POST etc.).

Security section

This section provides configuration for client authorization at the gateway for every endpoint.

BasicRecommended

AnonymousNo security

One type of security configuration is Basic authentication. The REST Connector waits for HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.

Parameter	Default value	Description
type	basic	Type of authorization.
username	username	Username for authorization.
password	password	Password for authorization.

Security section in configuration file will look like this:

    "security": {
      "type": "basic",
      "username": "username",
      "password": "password"
    }

Anonymous auth is the most simple option. It is useful for testing.

Parameter	Default value	Description
type	anonymous	Type of authorization.

Security subsection in configuration file will look like this:

    "security": {
      "type": "anonymous"
    }

Converter subsection

This subsection contains configuration for processing incoming messages.

Types of request converters:

json – Default converter
custom – Custom converter (You can write it by yourself, and it will use to convert incoming data.)

Json converter is default converter, it looks for deviceName, deviceType, attributes and telemetry in the incoming request from the client, with rules, described in this subsection:

Parameter	Default value	Description
type	json	Provides information to connector that default converter will be uses for converting data from the incoming request.
deviceNameExpression	Device ${name}	Simple JSON expression, uses for looking device name in the incoming message (value of the parameter “name” from the request will be used as device name).
deviceTypeExpression	default	Simple JSON expression, uses for looking device type in the incoming message (string “default” will be used as device type).
attributes		This subsection contains parameters of the incoming requests, that will be interpreted as attributes for the device.
… type	string	Type of incoming data for a current attribute.
… key	model	Simple JSON expression, uses for looking key in the incoming data, that will send to ThingsBoard instance as attribute key.
… value	${sensorModel}	Simple JSON expression, uses for looking value in the incoming data, that will send to ThingsBoard instance as value of key parameter.
timeseries		This subsection contains parameters of the incoming message, that will be interpreted as telemetry for the device.
… type	double	Type of incoming data for a current telemetry.
… key	temperature	Simple JSON expression, uses for looking key in the incoming message, that will send to ThingsBoard instance as attribute key.
… value	${temp}	Simple JSON expression, uses for looking value in the incoming message, that will send to ThingsBoard instance as value of key parameter.

Mapping subsection looks like:

    {
      "endpoint": "/test_device",
      "HTTPMethod": [
        "POST"
      ],
      "security":
      {
        "type": "basic",
        "username": "user",
        "password": "passwd"
      },
      "converter": {
        "type": "json",
        "deviceNameExpression": "Device ${name}",
        "deviceTypeExpression": "default",
        "attributes": [
          {
            "type": "string",
            "key": "model",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}"
          }
        ]
      }
    }

A custom converter is converter written for some device:

Parameter	Default value	Description
type	custom	Provides information to connector that custom converter will be uses for converting data from request.
deviceNameExpression	SuperAnonDevice	Device name.
deviceTypeExpression	default	Devcie type.
extension	CustomRESTUplinkConverter	Name of custom converter class.
extension-config		Configuration, for custom converter (You can put anything, there. It will be passed to the converter object on initialization).
key	Totaliser
datatype	float
fromByte	0
toByte	4
byteorder	big
signed	true
multiplier	1

Notate: Everything, you placed in the “converter” section will be passed to the custom converter as a configuration.

Mapping subsection in the configuration looks like:

      "converter": {
        "type": "custom",
        "deviceNameExpression": "SuperAnonDevice",
        "deviceTypeExpression": "default",
        "extension": "CustomRestUplinkConverter",
        "extension-config": [
          {
          "key": "Totaliser",
          "datatype": "float",
          "fromByte": 0,
          "toByte": 4,
          "byteorder": "big",
          "signed": true,
          "multiplier": 1
          }]
      }

Attribute update section

Configuration in this section are optional.
ThingsBoard allows to provision device attributes and fetch some of them from the device application. You can treat this as a remote configuration for devices. Your devices are able to request shared attributes from ThingsBoard. See user guide for more details.

The “attributeRequests” configuration allows configuring the format of the corresponding attribute request and response messages.

Parameter	Default value	Description
httpMethod	POST	HTTP method for request (GET, POST etc.).
SSLVerify	false	Verify or no SSL certificate on the server if available.
httpHeaders	{ “CONTENT-TYPE”: “application/json” }	Object contains additional HTTP headers for request.
security		Security for request:
type	basic	Security type for request to the server (basic or anonymous).
username	user	Username for basic type of the security.
password	passwd	Password for basic type of the security.
timeout	0.5	Timeout for request.
tries	3	Count of tries to send data
allowRedirects	true	Allow request redirection.
deviceNameFilter	*.REST$**	Regular expression device name filter, uses to determine, which function to execute.
attributeFilter	data	Regular expression attribute name filter, uses to determine, which function to execute.
requestUrlExpression	sensor/${deviceName}/${attributeKey}	JSON-path expression uses for creating url address to send a message.
valueExpression	{\”${attributeKey}\”:\”${attributeValue}\”}	JSON-path expression uses for creating the message data that will send to url.

The attributeUpdates section will look like:

  "attributeUpdates": [
      {
        "HTTPMethod": "POST",
        "SSLVerify": false,
        "httpHeaders": {
          "CONTENT-TYPE": "application/json"
        },
        "security": {
          "type": "basic",
          "username": "user",
          "password": "passwd"
        },
        "timeout": 0.5,
        "tries": 3,
        "allowRedirects": true,
        "deviceNameFilter": ".*REST$",
        "attributeFilter": "data",
        "requestUrlExpression": "sensor/${deviceName}/${attributeKey}",
        "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
      }
  ],

Server side RPC section

ThingsBoard allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

Configuration, provided in this section uses for sending RPC requests from ThingsBoard to device.

Parameter	Default value	Description
deviceNameFilter	.*	Regular expression device name filter, uses to determine, which function to execute.
methodFilter	echo	Regular expression method name filter, uses to determine, which function to execute.
requestUrlExpression	http://127.0.0.1:5001/${deviceName}	JSON-path expression, uses to create url address to send RPC request.
responseTimeout	1	Timeout for request.
httpMethod	GET	HTTP method for request (GET, POST etc.).
valueExpression	${params}	JSON-path expression, uses for creating data for sending.
timeout	0.5	Timeout for request.
tries	3	Count of tries to send data
httpHeaders	{ “CONTENT-TYPE”: “application/json” }	Object contains additional HTTP headers for request.
security		Security for request:
type	anonymous	Security type for request to the server (basic or anonymous).

  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "echo",
      "requestUrlExpression": "http://127.0.0.1:5001/${deviceName}",
      "responseTimeout": 1,
      "HTTPMethod": "GET",
      "valueExpression": "${params}",
      "timeout": 0.5,
      "tries": 3,
      "httpHeaders": {
        "Content-Type": "application/json"
      },
      "security": {
        "type": "anonymous"
      }
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "no-reply",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "HTTPMethod": "POST",
      "valueExpression": "${params}",
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    }
  ]

Next steps

Explore guides related to main ThingsBoard features:

Data Visualization - how to visualize collected data.
Device attributes - how to use device attributes.
Telemetry data collection - how to collect telemetry data.
Using RPC capabilities - how to send commands to/from devices.
Rule Engine - how to use rule engine to analyze data from devices.

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.