REST API Connectors

REST API Overview

The REST_API connector enables HTTP communication in both directions:

Client Mode - Make HTTP requests to external APIs triggered by MQTT messages
Server Mode - Expose HTTP endpoints that accept data and publish it to MQTT topics

REST API connectors are ideal for integrating with web services, webhooks, cloud APIs, and creating HTTP-to-MQTT bridges.

Basic Syntax

DEFINE CONNECTOR APIConnector WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
    ADD EVENT GetData
        WITH SOURCE_TOPIC "api/requests/data"
        WITH DESTINATION_TOPIC "api/responses/data"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/data"

How REST API Connectors Work

A REST API connector bridges the HTTP and MQTT worlds. It contains events that define what happens when data flows through—either from MQTT to HTTP (client mode) or from HTTP to MQTT (server mode).

Component	Purpose
`REST_API_CONFIG`	Connection settings—base URL, authentication, SSL, timeouts
`EVENT`	Defines a single HTTP operation with its trigger, method, and routing
`SOURCE_TOPIC`	MQTT topic that triggers the HTTP request (client mode)
`DESTINATION_TOPIC`	MQTT topic where results are published
`ENDPOINT`	The HTTP path to call (can include placeholders)

REST API Configuration

REST_API_CONFIG Parameters

Client Settings

string

required

Base URL for HTTP requests (e.g., https://api.example.com).

boolean

Enable HTTP client functionality. Default: false.

integer

Request timeout in seconds. Default: 30.

string

Default content type. Default: application/json.

Server Settings

boolean

Enable HTTP server functionality. Default: false.

integer

HTTP server port. Default: 8080.

Authentication

string

Basic authentication username.

string

Basic authentication password.

SSL/Security

boolean

Enable SSL/TLS. Default: false.

boolean

Ignore certificate validation errors. Default: false.

CORS

boolean

Enable CORS headers. Default: false.

string

Allowed CORS origins. Default: * (all).

Client Mode

Use client mode when your broker needs to call external APIs. An MQTT message triggers the HTTP request, and the response is published back to MQTT.

Event Configuration

Trigger & Routing

string

MQTT topic that triggers the HTTP request.

string

MQTT topic to publish HTTP response.

HTTP Request

string

HTTP method: GET, POST, PUT, DELETE, PATCH.

string

API endpoint path (supports placeholders).

string

Request body for POST/PUT (supports placeholders).

Placeholder Support

Use placeholders in endpoints and bodies to insert dynamic values from the MQTT message:

Placeholder	Description
`{payload}`	Full MQTT payload as-is
`{value.json}`	Parsed JSON payload
`{value.json.field}`	Specific field from JSON payload
`{source_topic}`	Original MQTT topic
`{timestamp}`	Message timestamp

A placeholder in ENDPOINT stays on the connector’s BASE_ADDRESS. A value that points at another host, such as /evil.example/x or https://evil.example/x, is refused, and the reply topic gets a RequestRejected error. An ENDPOINT you write as a full URL still uses that URL.

Client Examples

GET Request
POST Request
With Authentication

Fetch data from an external API when an MQTT message arrives:

DEFINE CONNECTOR WeatherAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openweathermap.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
    ADD EVENT GetWeather
        WITH SOURCE_TOPIC "weather/request"
        WITH DESTINATION_TOPIC "weather/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?q={value.json.city}&appid={value.json.apikey}"

When a message like {"city": "London", "apikey": "abc123"} arrives at weather/request, the connector calls the API and publishes the weather data to weather/response.

Send data to an external API:

DEFINE CONNECTOR NotificationAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.notification-service.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
    ADD EVENT SendNotification
        WITH SOURCE_TOPIC "notifications/send"
        WITH DESTINATION_TOPIC "notifications/result"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/notify"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{payload}"

The entire MQTT payload is forwarded as the HTTP request body using {payload}.

Use basic authentication for protected APIs:

DEFINE CONNECTOR AuthenticatedAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://secure-api.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USERNAME "api_user"
        WITH PASSWORD "api_secret"
        WITH USE_SSL "true"
    ADD EVENT SecureRequest
        WITH SOURCE_TOPIC "secure/request"
        WITH DESTINATION_TOPIC "secure/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/protected/data"

The username and password are sent as HTTP Basic Authentication headers automatically.

Server Mode

Use server mode when external systems need to send data to your broker via HTTP. The broker exposes an HTTP endpoint that accepts requests and publishes the data to MQTT topics.

Common use case: Your web application, mobile app, or third-party service needs to push data into the MQTT broker without implementing an MQTT client.

Why Use Server Mode?

Scenario	How Server Mode Helps
Web dashboards	Submit commands or data via simple HTTP POST
Mobile apps	Send sensor data without MQTT libraries
Webhooks	Receive callbacks from services like GitHub, Stripe, Slack
Legacy systems	Integrate systems that only support HTTP
Firewalled environments	Accept data through standard HTTP ports

Server Event Configuration

Endpoint & Method

string

The HTTP path to expose (e.g., /api/sensors).

string

HTTP method to accept: GET, POST, PUT, DELETE.

MQTT Routing

string

MQTT topic where incoming HTTP data is published.

Server Examples

Accept Sensor Data
Multiple Endpoints
Webhook Receiver
CORS for Web Apps

Expose an endpoint for devices to submit readings via HTTP:

DEFINE CONNECTOR SensorHTTPBridge WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
    ADD EVENT ReceiveSensorData
        WITH ENDPOINT "/api/sensors"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/from/http"

Usage: Send sensor data with a simple HTTP POST:

curl -X POST http://broker-ip:8080/api/sensors \
  -H "Content-Type: application/json" \
  -d '{"sensor_id": "temp-01", "value": 25.5}'

The data is published to sensors/from/http and available to all MQTT subscribers.

Expose different endpoints for different data types:

DEFINE CONNECTOR MultiEndpointAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
    
    ADD EVENT ReceiveTemperature
        WITH ENDPOINT "/api/temperature"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/temperature/http"
    
    ADD EVENT ReceivePressure
        WITH ENDPOINT "/api/pressure"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/pressure/http"
    
    ADD EVENT ReceiveCommands
        WITH ENDPOINT "/api/commands"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "commands/from/http"

Each endpoint connectors to a different MQTT topic for organized data handling.

Accept webhooks from external services:

DEFINE CONNECTOR WebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9000'
    
    ADD EVENT GitHubWebhook
        WITH ENDPOINT "/webhooks/github"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webhooks/github/events"
    
    ADD EVENT StripeWebhook
        WITH ENDPOINT "/webhooks/stripe"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webhooks/stripe/events"

Configure GitHub or Stripe to send webhooks to http://your-broker:9000/webhooks/github. Events appear on the corresponding MQTT topics.

Enable cross-origin requests for browser-based applications:

DEFINE CONNECTOR WebAppAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '3000'
        WITH ENABLE_CORS "true"
        WITH CORS_ORIGINS "https://app.example.com, https://admin.example.com"
    ADD EVENT SubmitData
        WITH ENDPOINT "/api/submit"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webapp/submissions"

Only requests from the specified origins are allowed. Use "*" for development (not recommended for production).

Combined Client and Server

A single connector can operate in both modes—accepting HTTP requests AND calling external APIs:

DEFINE CONNECTOR BidirectionalHTTP WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://external-api.com"
        WITH ENABLE_CLIENT "true"
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH USE_SSL "true"
        WITH ENABLE_CORS "true"
    
    // Server: Accept HTTP, publish to MQTT
    ADD EVENT ReceiveFromHTTP
        WITH ENDPOINT "/api/receive"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "http/incoming"
    
    // Client: MQTT triggers external HTTP call
    ADD EVENT CallExternalAPI
        WITH SOURCE_TOPIC "http/outgoing"
        WITH DESTINATION_TOPIC "http/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data"

Complete Examples

IoT Dashboard API
Third-Party Integration

Full API for a web dashboard to read sensor data and send commands:

DEFINE CONNECTOR DashboardAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
        WITH DEFAULT_CONTENT_TYPE "application/json"
    
    ADD EVENT PostSensorData
        WITH ENDPOINT "/api/sensors"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "dashboard/sensors/incoming"
    
    ADD EVENT PostCommand
        WITH ENDPOINT "/api/commands"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "commands/from/dashboard"
    
    ADD EVENT PostAlert
        WITH ENDPOINT "/api/alerts"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "alerts/from/dashboard"

Integrate with an external CRM or ERP system:

DEFINE CONNECTOR CRMIntegration WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.crm-system.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
    
    ADD EVENT CreateRecord
        WITH SOURCE_TOPIC "crm/create"
        WITH DESTINATION_TOPIC "crm/created"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/records"
        WITH HEADERS
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.data}"
    
    ADD EVENT UpdateRecord
        WITH SOURCE_TOPIC "crm/update"
        WITH DESTINATION_TOPIC "crm/updated"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/records/{value.json.id}"
        WITH BODY "{value.json.data}"
    
    ADD EVENT DeleteRecord
        WITH SOURCE_TOPIC "crm/delete"
        WITH DESTINATION_TOPIC "crm/deleted"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/v2/records/{value.json.id}"

Troubleshooting

Connection Timeout

Verify BASE_ADDRESS is correct
Check firewall allows outbound connections
Increase REQUEST_TIMEOUT if API is slow
Verify network connectivity

SSL/TLS Errors

Ensure USE_SSL matches the API requirements
For self-signed certificates, set IGNORE_CERT_ERRORS (not recommended for production)
Verify certificate chain is complete

Authentication Failed

Verify USERNAME and PASSWORD are correct
Check Authorization header format
Ensure API key is valid and not expired

CORS Errors

Enable CORS on the server: WITH ENABLE_CORS "true"
Configure specific allowed origins
Check browser console for specific CORS error messages

No Response Published

Verify DESTINATION_TOPIC is configured
Check MQTT broker connectivity
Monitor broker logs for errors

Best Practices

Use HTTPS in Production

Always use SSL/TLS for external API connections:

WITH USE_SSL "true"

Set Appropriate Timeouts

Configure timeouts based on expected API response times:

WITH REQUEST_TIMEOUT '30'

Handle Errors Gracefully

Subscribe to response topics to monitor API call results and handle failures in your Actions.

Secure Server Endpoints

When exposing HTTP server endpoints:

Use authentication where needed
Limit CORS origins to specific domains
Consider rate limiting at the network level

Use Environment-Specific Base URLs

Configure different base URLs for development and production environments.

REST API app templates

Ready-made client connectors (public test APIs, weather, Slack, GitHub, and planned enterprise systems such as SAP HANA and Salesforce) are listed in the REST API Apps catalog. Each app page shows the LoT connector definition, the event table, and how auth is passed.

That catalog does not include competitor brokers (HiveMQ, EMQX, ThingWorx) or OEM device connectors.

Discover templates and REST API apps: -listTemplates and -connectorCode

The broker ships every REST API app on this catalog as a template, keyed by its app code. Two broker commands, published to $SYS/Coreflux/Command, expose them (defined in Commands/Commands.cs):

Command	What it returns
`-listTemplates` (`--list-templates`)	JSON object keyed by template type, one card per built-in connector template and per REST API app.
`-connectorCode <type\|APP_CODE>` (`--connector-code`; alias `-routeCode`)	The JSON card for one template. The argument is a connector type such as `REST_API`, or a REST API app code such as `AIRTABLE`, `SAP_S4HANA_CLOUD` or `GEMINI_API`.

An app with one connector is keyed by its folder name, upper-cased with every non-alphanumeric run turned into _ (sap-s4hana-cloud becomes SAP_S4HANA_CLOUD). An app with several connectors keys each one by its connector name without the RestApi suffix (GeminiApiRestApi becomes GEMINI_API). The catalog lists every app code. Each card has this shape (from RouteHandler.BuildTemplatePayload):

{
  "type": "AIRTABLE",
  "baseType": "REST_API",
  "connector": true,
  "template": "DEFINE CONNECTOR #RouteName,string,...# WITH TYPE REST_API ...",
  "metadata": {
    "name": "Airtable",
    "image": "<base64 PNG>",
    "status": "beta",
    "category": "...",
    "description": "...",
    "doclink": "https://docs.coreflux.org/.../rest-api-apps/airtable",
    "license": "community",
    "minimumTier": "Community",
    "actionSlots": 5,
    "availableOnThisBroker": true,
    "requiredSecrets": ["AIRTABLE_API_TOKEN"]
  }
}

status is beta for every app today: the broker accepts no other value. The docs call this technical preview.
license is community when a Community broker can deploy the template, otherwise licensed. minimumTier is Community, Growth or Enterprise, actionSlots is the number of actions the connector registers, and availableOnThisBroker says whether the current license can deploy it.
requiredSecrets lists the broker secrets the template reads (GET SECRET or {secret.NAME}). Create them before you deploy.
connector is true and baseType is REST_API for every REST API app. For built-in connector templates connector is false and baseType equals type. The field keeps the name connector for compatibility; it marks a REST API app.
An app code is not a connector type: deploy the template with WITH TYPE REST_API, not WITH TYPE AIRTABLE.
template is the deployable connector code only. The ADD METADATA block is split off into metadata, because -addConnector rejects it.
#Name,type,description,regex,required# markers are Hub placeholders (for example #RouteName# and #BaseUrl#). Replace them with real values before you deploy with -addConnector (-addRoute remains a supported alias).

mosquitto_pub -t '$SYS/Coreflux/Command' -m "-listTemplates"
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AIRTABLE"

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

REST API Overview

Basic Syntax

How REST API Connectors Work

REST API Configuration

REST_API_CONFIG Parameters

Client Mode

Event Configuration

Placeholder Support

Client Examples

Server Mode

Why Use Server Mode?

Server Event Configuration

Server Examples

Combined Client and Server

Complete Examples

Troubleshooting

Best Practices

REST API app templates

Discover templates and REST API apps: -listTemplates and -connectorCode

Next Steps

Streaming Connectors

Connector Examples

​REST API Overview

​Basic Syntax

​How REST API Connectors Work

​REST API Configuration

​REST_API_CONFIG Parameters

​Client Mode

​Event Configuration

​Placeholder Support

​Client Examples

​Server Mode

​Why Use Server Mode?

​Server Event Configuration

​Server Examples

​Combined Client and Server

​Complete Examples

​Troubleshooting

​Best Practices

​REST API app templates

​Discover templates and REST API apps: -listTemplates and -connectorCode

​Next Steps

Streaming Connectors

Connector Examples

REST API Overview

Basic Syntax

How REST API Connectors Work

REST API Configuration

REST_API_CONFIG Parameters

Client Mode

Event Configuration

Placeholder Support

Client Examples

Server Mode

Why Use Server Mode?

Server Event Configuration

Server Examples

Combined Client and Server

Complete Examples

Troubleshooting

Best Practices

REST API app templates

Discover templates and REST API apps: -listTemplates and -connectorCode

Next Steps