REST Integration Guide

MaestroHub's REST connector bridges your pipelines with modern web services, business applications, and cloud platforms. Create reusable request templates, manage authentication centrally, and orchestrate API interactions alongside industrial protocols.

Overview

The REST connector supports:

• Multiple HTTP methods (GET, POST, PUT, PATCH) available as reusable functions within the connector
• Flexible authentication including API keys, OAuth 2.0, Basic, and custom headers
• Dynamic payload templating to merge pipeline values into query strings, headers, and bodies
• Secure connections with TLS enforcement, certificate pinning, and per-request overrides

When to Use REST Nodes

Use REST functions whenever you need to interact with MES, ERP, CMMS, or cloud services that expose HTTP-based APIs.

Connection Configuration

Creating a REST Connection

From Connections → New Connection → REST, configure the connection using the following reference tables.

REST API Connection Creation Fields

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this REST connection

2. REST Connection Settings

Field	Default	Description
Base URL	-	Base endpoint for the REST API (e.g., https://api.example.com) – required, must be a valid URL with domain or IP/localhost
Health Path	-	Optional relative path used for connection health checks (e.g., /health)
Request Timeout (ms)	30000	Maximum time to wait for a response before failing (0-600000 ms, 10 minutes max) – required
Skip Verify TLS	false	Do not verify the server's TLS certificate (insecure, not recommended for production)

URL Validation

• Must include protocol (http:// or https://)
• Host must be:
  • Valid domain with TLD (e.g., example.com)
  • IP address (IPv4 or IPv6)
  • localhost

3. Authentication

3a. Authentication Type Selection

Field	Default	Description
Authentication Type	none	Choose authentication method (none / basic / apikey / webtoken) – required

3b. Basic Auth

(Only displayed when Authentication Type = "basic")

Field	Default	Description
Username	-	Username for Basic Authentication – required
Password	-	Password for Basic Authentication – required

3c. API Key

(Only displayed when Authentication Type = "apikey")

Field	Default	Description
API Key Location	header	Where to send the API key (header / query / body) – required
Key Name	-	Header/query/body field name for the API key (e.g., X-API-Key or api_key) – required
API Key Value	-	The actual API key value – required

API Key Location Options

• Header: Send API key in HTTP header
• Query Param: Send API key as URL query parameter
• Body: Send API key in request body

3d. Web Token (OAuth/JWT)

(Only displayed when Authentication Type = "webtoken")

Field	Default	Description
Token Endpoint URL	-	URL to fetch the authentication token (e.g., https://auth.service.com/token) – required, must be valid URL
Token Request Headers	-	Optional headers to send with the token request (key-value pairs)
Body Encoding	json	How to encode the token request body (json / form / raw) – required
Token Request Body	-	Body content to send to token endpoint (JSON format) – optional, supports parameters
Attach Token As Header	Authorization	Header name to attach the token to subsequent requests
Add 'Bearer ' prefix	true	Prepends Bearer to the token when attaching to the header
Token Path in Response	-	Dot-notation path to extract token from response (e.g., access.token or data.authToken) – required

Body Encoding Options

• JSON: application/json content type
• Form URL Encoded: application/x-www-form-urlencoded content type
• Raw: Plain text or custom encoding

Example Token Request Body

{
  "client_id": "rest-service",
  "client_secret": "((clientSecret))",
  "grant_type": "client_credentials",
  "scope": "api.read"
}

4. Advanced Settings

4a. Default Headers

Field	Default	Description
Default Headers		Key-value pairs sent with all REST requests for this connection. Function-level headers override these when keys conflict.

Header Editor Features

• Add/remove multiple headers
• Validation for header names and values
• Warning when authentication-related headers are detected

Common Headers

• Content-Type: application/json
• Accept: application/json
• User-Agent: MaestroHub/1.0
• X-Custom-Header: custom-value

5. Connection Labels

Field	Default	Description
Labels	-	Key-value pairs to categorize and organize this REST connection (max 10 labels)

Example Labels

• environment: production – Deployment environment
• team: api – Responsible team
• protocol: rest – Connection protocol
• region: us-east-1 – Geographical region

Authentication Type Validation Rules

Authentication Type	Required Fields
None	No additional fields required
Basic Auth	Username AND Password must both be provided
API Key	API Key Location, Key Name, AND API Key Value must all be provided
Web Token	Token Endpoint URL AND Token Path in Response must both be provided

Notes

• TLS Certificate Verification: When "Skip Verify TLS" is enabled, the server's certificate will not be validated. This is insecure and should only be used for development/testing.
• Authentication Priority: The system prevents mixing authentication methods. Only fields for the selected authentication type are sent to the backend.
• Password/Secret Masking: When editing an existing connection, sensitive fields (passwords, API keys, tokens) are masked with ******** and only updated if changed.
• Default Headers Warning: The system warns you if default headers contain authentication-related keys (authorization, token, api-key, etc.), suggesting use of the Authentication tab instead.
• URL Format: Base URL must include the protocol (http:// or https://) and a valid host.
• Health Check: If a Health Path is provided, it will be used for connection health monitoring.
• Timeout Range: Request timeout must be between 0 ms (no timeout) and 600000 ms (10 minutes).
• Headers Editor: Provides visual editor for managing key-value pairs with validation.
• Web Token Flow:
  • System requests token from Token Endpoint URL with provided headers/body.
  • Extracts token using Token Path in Response.
  • Attaches token to subsequent requests using specified header name.
  • Optionally prepends Bearer for OAuth 2.0 compatibility.
• Function-level Overrides: Connection-level settings (headers, authentication) can be overridden at the function level.

Function Builder

Creating REST Functions

Once the connection is saved:

1. Go to Functions → New Function
2. Select REST HTTP Request as the function type
3. Pick the REST connection profile
4. Define the HTTP method, path, headers, query parameters, and payload template

Design reusable REST requests with method, path, and payload templates

GET Function

Purpose: Perform HTTP GET requests to retrieve data from REST APIs. Used for reading data without modifying server state.

Configuration Fields

Field	Type	Required	Default	Description
Path	String	Yes	/	URL path to append to base URL (supports parameters). Example: /users/((userId))
URL	String	No	-	Override base URL for this function (full URL)
Headers	Object	No	{}	Custom headers for this request (key-value pairs). These override connection-level headers.
Query Parameters	Object	No	{}	URL query parameters (key-value pairs). Appended as ?key=value to URL.
Expected Status	Array	No	[200]	Expected HTTP status codes for successful responses
Response Format	String	No	json	Expected response format: json, xml, text, or binary
Timeout (ms)	Number	No	30000	Request timeout in milliseconds (1-300000)

Use Cases: Fetch user data, retrieve resource lists, get status information, read API endpoints

POST Function

Purpose: Perform HTTP POST requests to create new resources or submit data to REST APIs. Used for creating new data or triggering actions on the server.

Configuration Fields

Field	Type	Required	Default	Description
Path	String	Yes	/	URL path to append to base URL (supports parameters). Example: /users
Body (JSON)	String	Yes	{}	JSON request body (supports parameters). Example: {"name": "((name))"}
Content Type	String	Yes	application/json	MIME type of the request body (application/json, text/plain, application/xml, etc.)
URL	String	No	-	Override base URL for this function (full URL)
Headers	Object	No	{}	Custom headers for this request (key-value pairs). These override connection-level headers.
Query Parameters	Object	No	{}	URL query parameters (key-value pairs). Appended as ?key=value to URL.
Expected Status	Array	No	[200]	Expected HTTP status codes for successful responses
Response Format	String	No	json	Expected response format: json, xml, text, or binary
Timeout (ms)	Number	No	30000	Request timeout in milliseconds (1-300000)

Use Cases: Create new records, submit forms, trigger actions, upload data to API

PUT Function

Purpose: Perform HTTP PUT requests to update existing resources completely. Used for full updates where the entire resource is replaced with new data.

Configuration Fields

Field	Type	Required	Default	Description
Path	String	Yes	/	URL path to append to base URL (supports parameters). Example: /users/((userId))
Body (JSON)	String	Yes	{}	JSON request body (supports parameters). Example: {"name": "((name))"}
Content Type	String	Yes	application/json	MIME type of the request body (application/json, text/plain, application/xml, etc.)
URL	String	No	-	Override base URL for this function (full URL)
Headers	Object	No	{}	Custom headers for this request (key-value pairs). These override connection-level headers.
Query Parameters	Object	No	{}	URL query parameters (key-value pairs). Appended as ?key=value to URL.
Expected Status	Array	No	[200]	Expected HTTP status codes for successful responses
Response Format	String	No	json	Expected response format: json, xml, text, or binary
Timeout (ms)	Number	No	30000	Request timeout in milliseconds (1-300000)

Use Cases: Replace entire records, update complete resources, overwrite data, full resource updates

PATCH Function

Purpose: Perform HTTP PATCH requests to partially update existing resources. Used for partial updates where only specific fields are modified.

Configuration Fields

Field	Type	Required	Default	Description
Path	String	Yes	/	URL path to append to base URL (supports parameters). Example: /users/((userId))
Body (JSON)	String	Yes	{}	JSON request body (supports parameters). Example: {"status": "((status))"}
Content Type	String	Yes	application/json	MIME type of the request body (application/json, text/plain, application/xml, etc.)
URL	String	No	-	Override base URL for this function (full URL)
Headers	Object	No	{}	Custom headers for this request (key-value pairs). These override connection-level headers.
Query Parameters	Object	No	{}	URL query parameters (key-value pairs). Appended as ?key=value to URL.
Expected Status	Array	No	[200]	Expected HTTP status codes for successful responses
Response Format	String	No	json	Expected response format: json, xml, text, or binary
Timeout (ms)	Number	No	30000	Request timeout in milliseconds (1-300000)

Use Cases: Update specific fields, partial resource updates, status changes, modify individual properties

Using Parameters

REST functions expose parameters defined with ((parameterName)) syntax and validate them at runtime.

Configuration	Description	Example
Type	Coerce incoming values	string, number, boolean, datetime, json, array
Required	Ensure mandatory parameters are set	Required / Optional
Default Value	Populate sensible defaults	'open', NOW(), {}
Description	Provide guidance for callers	"ISO timestamp for incremental sync"

Parameter validation, defaults, and helper text for REST requests

Pipeline Integration

Use the REST connection functions you build here as nodes inside the Pipeline Designer to call external services alongside the rest of your automation logic. Drop in the GET, POST, or other HTTP node, bind parameters to upstream outputs or constants, and shape retries or error branches to suit each API.

If you are designing larger orchestrations, the Connector Nodes page shows how REST nodes complement other connectors in multi-step workflows.

REST node with connection, function, and parameter bindings

Common Use Cases

ERP or MES Sync

Pull schedules, work orders, or inventory levels from enterprise systems and propagate updates back after machine execution.

Notifications and Alerts

Send webhooks to Microsoft Teams, Slack, or custom services when pipeline conditions trigger alarms or thresholds.

Data Enrichment

Augment sensor data with contextual information from REST APIs (equipment metadata, operator rosters, weather feeds) before storing in historians.