REST

The REST Connector starts an HTTP(S) server on the gateway, creates API endpoints, and forwards incoming request data to ThingsBoard as device attributes and telemetry. It can also push data to external HTTP(S) APIs based on attribute updates and RPC commands received from ThingsBoard.

To enable this connector, add it to the connectors list in tb_gateway.json — see the General Configuration reference.

The connector reads its settings from a JSON file. Below is a full example with two mapping entries — the first uses a JSON converter with basic auth, the second uses a custom converter with anonymous auth:

{
  "server": {
    "host": "127.0.0.1",
    "port": 5000,
    "SSL": false
  },
  "mapping": [
    {
      "endpoint": "/test_device",
      "HTTPMethods": ["POST"],
      "security": {
        "type": "basic",
        "username": "username",
        "password": "password"
      },
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpression": "Device ${name}",
          "deviceNameExpressionSource": "request",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "default"
        },
        "attributes": [
          { "key": "model",       "type": "string", "value": "${sensorModel}" }
        ],
        "timeseries": [
          { "key": "temperature", "type": "double", "value": "${temp}" },
          { "key": "humidity",    "type": "double", "value": "${hum}" },
          { "key": "combine",     "type": "string", "value": "${hum}:${temp}" }
        ]
      }
    },
    {
      "endpoint": "/anon2",
      "HTTPMethods": ["POST"],
      "security": { "type": "anonymous" },
      "converter": {
        "type": "custom",
        "deviceInfo": {
          "deviceNameExpression": "SuperAnonDevice",
          "deviceNameExpressionSource": "constant",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "default"
        },
        "extension": "CustomRestUplinkConverter",
        "extensionConfig": {
          "key": "Totaliser",
          "datatype": "float",
          "fromByte": 0,
          "toByte": 4,
          "byteorder": "big",
          "signed": true,
          "multiplier": 1
        }
      }
    }
  ],
  "requestsMapping": {
    "attributeRequests": [],
    "attributeUpdates": [],
    "serverSideRpc": []
  }
}

Configures the HTTP(S) server the connector starts on the gateway.

{
  "server": {
    "host": "127.0.0.1",
    "port": 5000,
    "SSL": true,
    "security": {
      "cert": "~/ssl/cert.pem",
      "key": "~/ssl/key.pem"
    }
  }
}

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

An array of endpoint definitions. Each entry creates one HTTP endpoint on the gateway server, defines the allowed HTTP methods, the authorization scheme for incoming requests, and how to convert the request payload into ThingsBoard device data.

Per-endpoint authorization for incoming client requests.

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

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

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

Defines how the incoming request payload is converted to ThingsBoard device data.

curl -X POST http://127.0.0.1:5000/test_device \
  -H "Content-Type: application/json" \
  -u username:password \
  -d '{
        "name": "SensorA",
        "sensorModel": "TX100",
        "temp": 23.5,
        "hum": 56.2,
        "timestampField": "10.11.24 14:30:00.000"
      }'

curl -X POST "http://127.0.0.1:5000/test_device" \
  -u "username:password" \
  -F 'name=SensorA' \
  -F 'sensorModel=TX100' \
  -F 'temp=23.5' \
  -F 'hum=56.2' \
  -F 'timestampField=10.11.24 14:30:00.000'

{
  "endpoint": "/test_device",
  "HTTPMethods": ["POST"],
  "security": {
    "type": "basic",
    "username": "username",
    "password": "password"
  },
  "converter": {
    "type": "json",
    "deviceInfo": {
      "deviceNameExpression": "Device ${name}",
      "deviceNameExpressionSource": "request",
      "deviceProfileExpressionSource": "request",
      "deviceProfileExpression": "default"
    },
    "attributes": [
      {
        "key": "model",
        "type": "string",
        "value": "${sensorModel}"
      }
    ],
    "timeseries": [
      {
        "key": "temperature",
        "type": "double",
        "value": "${temp}"
      },
      {
        "key": "humidity",
        "type": "double",
        "value": "${hum}",
        "tsField": "${timestampField}",
        "dayfirst": true
      }
    ]
  }
}

{ "key": "combine", "type": "string", "value": "${hum}:${temp}" }

{
  "type": "custom",
  "deviceInfo": {
    "deviceNameExpression": "SuperAnonDevice",
    "deviceNameExpressionSource": "constant",
    "deviceProfileExpressionSource": "constant",
    "deviceProfileExpression": "default"
  },
  "extension": "CustomRestUplinkConverter",
  "extensionConfig": {
    "key": "Totaliser",
    "datatype": "float",
    "fromByte": 0,
    "toByte": 4,
    "byteorder": "big",
    "signed": true,
    "multiplier": 1
  }
}

Optional. Controls what HTTP response body the gateway returns to the client after processing the request. Three variants are supported:

1. Default — returns only an HTTP status code (no response body). No extra configuration needed.

2. Hardcoded response body — always returns the same static text:

{
  "endpoint": "/test_device",
  "HTTPMethods": ["POST"],
  "security": { "type": "anonymous" },
  "converter": { "type": "json" },
  "response": {
    "successResponse": "OK",
    "unsuccessfulResponse": "Error"
  }
}

3. Advanced — ThingsBoard rule chain response: the gateway forwards the request to ThingsBoard, waits for a rule chain to set a shared attribute, and returns that attribute value as the HTTP response.

{
  "endpoint": "/test_device",
  "HTTPMethods": ["POST"],
  "security": { "type": "anonymous" },
  "converter": { "type": "json" },
  "response": {
    "responseExpected": true,
    "timeout": 120,
    "responseAttribute": "result"
  }
}

To use the advanced response, configure a rule chain in ThingsBoard that sets the shared attribute named in responseAttribute on the device:

Rule chain that sets a shared attribute as the HTTP response. Yellow rule node — triggers the attribute write. Blue rule node — writes the response value to the shared attribute.

Optional. Configures attribute requests, attribute updates, and server-side RPC handling.

Lets a device request its own client-side or shared attributes from ThingsBoard by sending an HTTP request to a dedicated endpoint on the gateway.

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

To request multiple attributes in a single call, add multiple JSON-path expressions separated by a comma in attributeNameExpression:

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

When a shared attribute is updated in ThingsBoard, the gateway sends an HTTP request to an external URL on the device.

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

Maps ThingsBoard RPC commands to outgoing HTTP requests sent to the device.

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

Every telemetry and attribute key also has a built-in GET and SET RPC method available automatically. The required parameters are requestUrlExpression, responseTimeout, HTTPMethod, and valueExpression. See the Reserved RPC methods guide for details.