REST API Call Node

Use this node whenever a rule chain needs to reach outside ThingsBoard — send a command to a third-party device management system, call a webhook, fetch data from an external API, or trigger a cloud function. It supports GET, POST, PUT, PATCH, and DELETE with configurable authentication, proxy, and concurrency controls.

The full URL of the external endpoint. Supports templatization — use ${metadata.key} and ${data.key} to build dynamic URLs, for example:

https://api.example.com/v1/devices/${metadata.deviceId}/commands

GET, POST, PUT, PATCH, or DELETE.

Key-value pairs of HTTP headers to include in the request. Both keys and values support templatization.

Controls how message data is processed before sending:

• Disabled (default) — message data is sent as-is.
• Enabled — if the message data is a JSON-encoded string (wrapped in double quotes), the outer JSON encoding is removed before sending.

• Disabled (default) — the request body contains the message data for POST, PUT, PATCH, and DELETE methods.
• Enabled — no request body is sent, even for methods that typically include one.

Enable proxy routing when the ThingsBoard server cannot reach the endpoint directly.

System properties (at least one set must be configured when using system proxy):

Manual proxy configuration (when system proxy is disabled):

Controlled by the ACTORS_RULE_EXTERNAL_NODE_FORCE_ACK environment variable (applies to all external nodes).

• Disabled (default) — the original incoming message is held until the HTTP request completes, then transformed with the response data and passed to the next node.
• Enabled — the incoming message is acknowledged immediately; once the request completes, a new message is created with the response data and added to the queue. This prevents processing timeouts for slow endpoints.

For each incoming message, the node:

1. If Force acknowledgement is enabled, acknowledges the incoming message immediately.
2. If Max parallel requests is configured, waits for an available slot (failing with a timeout error if none becomes available within the read timeout).
3. Resolves the Endpoint URL pattern by substituting ${metadata.key} and ${data.key} templates.
4. Prepares HTTP headers — configured headers are processed for templates; Basic credentials are encoded and added as the Authorization header.
5. Prepares the request body:
   • If Without request body is enabled, no body is sent.
   • Otherwise, for POST/PUT/PATCH/DELETE: if attachments is in metadata (blob entity IDs), the first blob’s content is used; otherwise, the message data is used. If Parse to plain text is enabled, JSON-encoded strings are unwrapped.
6. Sends the HTTP request to the endpoint.
7. On response:
   • 2xx status: response information is added to the message, forwarded via Success.
   • Non-2xx or error: error information is added to the message, forwarded via Failure.
8. If Max parallel requests is configured, releases the slot.

Message data is replaced with the response body ({} if empty). The following keys are added to metadata:

Message data remains unchanged. The following keys are added to metadata:

A smart lock device needs to send an unlock command to an external device management system and receive the execution result. The endpoint requires Basic authentication.

Incoming message (originator: Smart Lock device):

Data:

{
  "command":  "unlock",
  "duration": 30,
  "reason":   "owner_request"
}

Metadata:

{
  "deviceId":   "lock-bedroom-01",
  "deviceType": "smartLock"
}

Node configuration:

{
  "restEndpointUrlPattern":   "https://api.smart-home.com/v1/devices/${metadata.deviceId}/commands",
  "requestMethod":            "POST",
  "headers":                  { "Content-Type": "application/json" },
  "readTimeoutMs":            5000,
  "maxParallelRequestsCount": 10,
  "credentials": {
    "type":     "basic",
    "username": "api-client",
    "password": "secure-password"
  }
}

The node resolves the URL to https://api.smart-home.com/v1/devices/lock-bedroom-01/commands and adds Authorization: Basic YXBpLWNsaWVudDpzZWN1cmUtcGFzc3dvcmQ=.

Outgoing message (routed via Success):

Data:

{
  "commandId":   "cmd-98765",
  "status":      "executed",
  "executedAt":  "2023-01-01T10:30:00Z",
  "result": {
    "success":    true,
    "lockState":  "unlocked",
    "autoLockIn": 30
  }
}

Metadata includes original fields plus statusCode: "200", status: "OK", statusReason: "OK", and any response headers such as Content-Type and X-Request-Id.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbRestApiCallNodeConfiguration",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "restEndpointUrlPattern":   { "type": "string", "minLength": 1 },
    "requestMethod":            { "type": "string", "enum": ["GET","POST","PUT","PATCH","DELETE"] },
    "headers":                  { "type": "object", "additionalProperties": { "type": "string" } },
    "readTimeoutMs":            { "type": "integer", "minimum": 0 },
    "maxParallelRequestsCount": { "type": "integer", "minimum": 0 },
    "parseToPlainText":         { "type": "boolean" },
    "enableProxy":              { "type": "boolean" },
    "useSystemProxyProperties": { "type": "boolean" },
    "proxyHost":                { "type": "string" },
    "proxyPort":                { "type": "integer", "minimum": 1, "maximum": 65535 },
    "proxyUser":                { "type": "string" },
    "proxyPassword":            { "type": "string" },
    "credentials":              { "type": "object" },
    "ignoreRequestBody":        { "type": "boolean" },
    "maxInMemoryBufferSizeInKb":{ "type": "integer", "minimum": 1 }
  }
}