The REST API Connector sends HTTP or HTTPS requests from SIA Connect to an external API. Use it to retrieve a response at a configured interval or to send data when a mapping writes to an item.

This guide explains how to configure an instance and items, add authentication and headers, control request-body encoding, interpret responses, and troubleshoot requests.

Before you begin

Make sure that:

• The REST API Connector is installed.
• SIA Connect can reach the API host through its configured network and DNS settings.
• You know the API base URL, endpoint path, HTTP method, authentication requirements, headers, and body format.
• The API credentials have only the permissions required for the intended request.
• You have a safe test endpoint or test record available when the request changes data.

Understand when requests are sent

Create a REST API instance

1. In the Edge Portal, open Instances.
2. Select Create instance.
3. Select the REST API Connector.
4. Enter a unique name for the instance.
5. Enter the API base URL in Address.
6. Configure the remaining instance parameters.
7. Select Create.

Instance parameters

Add request headers

Enter each header inside braces using {Header-Name: value}. Place multiple headers directly after one another.

{Accept-Language: en-US}{X-API-Key: example-key}

Default headers from the instance and headers from the item are combined. Use default headers for values required by every item. Use item headers for endpoint-specific values.

For bearer-token authentication, add an authorization header:

{Authorization: Bearer example-token}

Create a REST API item

1. Open the REST API instance.
2. Open the Items tab.
3. Select Create item.
4. Enter a unique item name.
5. Enter the endpoint path and select the HTTP method.
6. Configure any item-specific headers, request body, and body encoding.
7. Configure the read and write behavior required for the item.
8. Select Create.

Item parameters

The Connector joins the instance Address and item Endpoint with one slash. For example, https://api.example.com/v1 and /measurements become https://api.example.com/v1/measurements.

Configure a request that runs at an interval

Use an item with read enabled when the request must run at regular intervals.

1. Create or edit the item.
2. Select the required HTTP method.
3. Enter the endpoint path.
4. Add any required headers and body.
5. Enable reading and configure a suitable read interval.
6. Save the item.
7. Check the item value and status after the first request.

For a successful HTTP response with a status from 200 through 299, the complete response body is stored as the item value. The Connector does not extract individual properties from a JSON response.

Send mapped data to an API

Use a writable item and a mapping when another item value must trigger the request.

1. Create or edit the REST API item.
2. Select POST or PUT, as required by the API.
3. Enter the endpoint and required headers.
4. Leave Body empty if the incoming mapped value must become the request body.
5. Enable writing and save the item.
6. Create a mapping from the source item to the REST API item.
7. Trigger a test value and check the REST API item's value, status, and events.

If the item Body contains content, that content is sent instead of the mapped value. This behavior is useful when a mapping should trigger a fixed request.

Choose the body encoding

For a URL-encoded form request, add the following item header:

{Content-Type: application/x-www-form-urlencoded}

When the final request body is valid JSON, the Connector automatically adds Accept: application/json and Content-Type: application/json. Request bodies are sent as UTF-8, including non-ASCII characters.

Interpret responses

A failed HTTP request is reported as Code: status response, where status is the HTTP status and response is the body returned by the API.

Verify the configuration

1. Use a known safe request and test value.
2. Confirm that the instance and item do not report errors.
3. Check that the API received the expected method, URL, headers, and body.
4. Confirm that the response body appears as the item value.
5. For a mapped write, verify that the request runs only when the intended mapping is triggered.
6. Set a read interval that respects the API's rate limits.

Troubleshoot the REST API Connector

The host cannot be resolved or reached

Confirm that the Address contains the correct scheme and hostname. Test name resolution and network access from SIA Connect. Check its DNS configuration, default route, firewall rules, and the API port. Increase the connection timeout only when establishing the connection legitimately takes longer.

The API returns 401 or 403

Check the credentials and permissions. Enter Basic authentication credentials in the instance Username and Password fields. For a bearer token or API key, confirm the required header name, prefix, and token value.

The API returns 404

Check the combined instance Address and item Endpoint. Confirm the API version and path. Remember that the Connector adds one slash between the two values.

The API returns a redirect

The Connector does not follow redirects automatically. Replace the Address or Endpoint with the final URL supplied by the API.

The API returns 400, 415, or 422

Check the request method, body format, body encoding, and Content-Type. Use None or Auto for JSON. Use URL encode and add Content-Type: application/x-www-form-urlencoded when the API expects form data.

A header is missing from the request

Confirm that every header uses the complete {Header-Name: value} format. Check both the instance Default headers and the item Header fields.

The mapped value is not sent

Clear the REST API item's Body field. A configured body takes precedence over an incoming mapped value.

The response contains JSON but individual values are unavailable

The Connector stores the complete response body as text. It does not extract JSON properties into separate items. Process or transform the response in another component when individual fields are required.

The API reports too many requests

Increase the item read interval and check the API's rate-limit requirements. Avoid enabling polling when the request only needs to run after a mapped value changes.

Characters are displayed incorrectly by the receiving service

The Connector sends request bodies as UTF-8. Confirm that the API expects UTF-8 and add an appropriate Content-Type header with a UTF-8 charset if the service requires it.

An HTTPS endpoint uses a certificate

Security limitation: The current Connector does not validate the remote TLS certificate. Use only trusted endpoints and networks. Do not treat a successful HTTPS connection as proof of the remote server's identity.

More diagnostic information is required

Review the system logs for the requested URL, HTTP status, and transport error. Debug logs can include request headers, bodies, and responses. Restrict access to the logs and remove or rotate exposed credentials after troubleshooting.

Related articles

• Install and manage Connectors
• Create and edit instances
• Create and edit items
• Create and edit mappings
• Change network settings in the Edge Portal
• Configure and review system logs