Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
IoT Gateway
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Configuration guides > REST Connector
Getting Started
Installation
On this page

REST Connector Configuration

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.

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

{
  "host": "127.0.0.1",
  "port": 5000,
  "SSL": false,
  "security": {
    "cert": "~/ssl/cert.pem",
    "key": "~/ssl/key.pem"
  },
  "mapping":[
    {
      "endpoint": "/test_device",
      "HTTPMethods": [
        "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",
      "HTTPMethods": [
        "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

With SSLRecommended
Without SSLNo security
Parameter Default value Description
host 127.0.0.1 Domain address or ip of the server.
port 5000 Port of the server.
SSLVerify true Verify or no SSL certificate on the server if available.
cert path_to_the_pem_file Path to certificate file.
key path_to_the_key_file Path to private key file.

Configuration section will look like:

1
2
3
4
5
6
7
8
9

{
  "host": "127.0.0.1",
  "port": "5000",
  "SSL": true,
  "security": {
    "cert": "~/ssl/cert.pem",
    "key": "~/ssl/key.pem"
  }
}
Parameter Default value Description
host 127.0.0.1 Domain address or ip of the server.
port 5000 Port of the server.
SSLVerify false Verify or no SSL certificate on the server if available.

Configuration section will look like:

1
2
3
4
5

{
  "host": "127.0.0.1",
  "port": "5000",
  "SSL": false
}

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.
HTTPMethods GET HTTP methods 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:

1
2
3
4
5

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

Also, make sure that your request have Authorization header with provided credentials.

If you are using cURL, the request will look like:

1
2

curl --user username:password -H "Content-Type: application/json" -X POST \
    -d '{"sensorName": "SN-001", "sensorModel": "example"}' http://127.0.0.1:5000/my_devices

Or if you are using Postman or Insomnia, simply enable Basic auth.

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:

1
2
3

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

Converter subsection

This subsection contains configuration for processing incoming messages.

Types of request converters:

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

Connector won’t pass the None value from the converter

jsonRecommended if json will be received in the request
customRecommended if bytes or anything else will be received in the request

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.
Doc info icon

Parameters in attributes and telemetry section may differ from those presented above, but will have the same structure.

Mapping subsection looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

    {
      "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}"
          }
        ]
      }
    }

Also, you can combine values from MQTT message in attributes, telemetry and serverSideRpc section, for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

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  
Doc info icon


Custom converter usually needed if you want to collect data from some device with not regular structure in response or when the data needs some processing before sending it to the ThingsBoard.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

      "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
          }]
      }
Doc info icon

It is also may to parse query parameters from the URL if you are using a GET request.

Response

Response in REST Connector can have 3 variants of configuration:

  1. Default response (without extra configuration, return only HTTP Status Code);

  2. Hardcoded response body, for this option you have to specify a new section and 2 new optional parameters as in the example below:

    Parameter Default value Description
    response   The response that will be returned on every request to the server
    … successResponse OK Only if the response status is 200
    … unsuccessfulResponse Error Only if the response status different from 200
  3. ADVANCED the remote response that will return by ThingsBoard.

    1. To configure that variant you have to specify a new section in the config file as in the example below:

      Parameter Default value Description
      response   Boolean value for on/off returning a response
      … responseExpected true Timeout for request.
      … timeout 120 Only if the response status different from 200
      … responseAttribute result Shared attribute name which response will be return

    2. Configure RuleChain in ThingsBoard: image Finally, you have to configure rule node:

      1. Yellow Rule Node image
      2. Blue Rule Node image

Attribute request section

Configuration in this section are optional.

In order to request client-side or shared device attributes to ThingsBoard server node, Gateway allows sending attribute requests.

Parameter Default value Description
endpoint /sharedAttributes Url address of the endpoint.
type shared The type of requested attribute can be “shared” or “client”.
HTTPMethods [”POST”] Allowed methods
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 10.0 Timeout for request.
deviceNameExpression ${deviceName} JSON-path expression, for looking the device name.
attributeNameExpression ${attribute} JSON-path expression, for looking the attribute name.

The attributeRequests section will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

"attributeRequests": [
  {
    "endpoint": "/sharedAttributes",
    "type": "shared",
    "HTTPMethods": [
      "POST"
    ],
    "security": {
      "type": "anonymous"
    },
    "timeout": 10.0,
    "deviceNameExpression": "${deviceName}",
    "attributeNameExpression": "${attribute}"
  }
]

Also, you can request multiple attributes at once. Simply add one more JSON-path to attributeNameExpression parameter. For example, we want to request two shared attributes in one request, our config will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

"attributeRequests": [
  {
    "endpoint": "/sharedAttributes",
    "type": "shared",
    "HTTPMethods": [
      "POST"
    ],
    "security": {
      "type": "anonymous"
    },
    "timeout": 10.0,
    "deviceNameExpression": "${deviceName}",
    "attributeNameExpression": "${pduAttribute}, ${versionAttribute}"
  }
]

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

  "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).
Doc info icon

There are 2 types of the RPC calls:

  1. With reply, after sending request the gateway will wait for response and send it to ThingsBoard.
  2. With no reply, after sending request the gateway will not wait for response.

Examples for both methods provided below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

  "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.hum}",
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    }
  ]

Also, every telemetry and attribute parameter has built-in GET and SET RPC methods out of the box, so you don’t need to configure it manually. To use them, make sure you set all required parameters (in the case of REST Connector, these are the following: requestUrlExpression, responseTimeout, HTTPMethod, valueExpression). See the guide.

Next steps

Explore guides related to main ThingsBoard features: