Connect IoT - Rest Client#

This driver allows connection and exchange data using a stateless communication with a Rest Server.

Data Types#

These are the supported specific data types:

Name	Description
String	String value
Boolean	Boolean value
Integer	Integer value
Double	Double value
DateTime	DateTime value
Object	Structure value

Table: Rest specific data types

Protocol Parameters#

The protocol supports the following parameters, used to define the communication parameters, as well as the expected behavior of the driver:

Name	Type	Possible Values	Default Value	Description
baseUrl	string		`127.0.0.1`	Hostname or IP-Address of the REST server. The host can be a fully qualified domain or IP address. Note: Base URL must not include query string parameters. For example, api.example.com/v1
port	integer		`80`	Port number of the REST server.
protocol	enum	`HTTP` `HTTPS`	`HTTP`	The protocol used for fetching resources.
authenticationMode	enum	`None` `BasicAuthentication` `BearerToken` `APIKey`	`None`	The authentication mode can be: Basic Authentication (username and password) BearerToken (authentication token, for example, PAT) API Key (api authentication token)
username	string			Username to use for REST server authentication.
password	password			Password to use for REST server authentication.
authenticationToken	text			API-Key or Bearer Token. The bearer token used for REST server authentication. Bearer tokens are sent in the 'Authorization' header of HTTP requests and are prefixed with the word 'Bearer,' for example, Authorization: Bearer . PATs are supported and are commonly used to authenticate API requests made by scripts, command-line tools, or applications on behalf of a user. An API Key, also known as an Application Programming Interface Key, is a type of security credential used to authenticate and authorize access to web-based services, APIs, or resources.
apiKeyTransmitter	enum	`Header` `Cookie` `QueryParameter`	`Header`	Where the API key is sent: as a request header, a cookie, or a query parameter.
apiKeyName	string			Defines an API key name to be sent either as request header, cookie or query parameter. For example, 'X-API-KEY'
clientCertificate	text			Own client certificate - can be either a path to a file or the contents of the file in plain text. Format should be 'pem'.
clientPrivateKey	text			Own client private key - can be either a path to a file or the contents of the file in plain text. Format should be 'pem'.
certificateAuthority	text			Certificate Authority - can be either a path to a file or the contents of the file in plain text. Format should be 'pem'. The certificateAuthority property is used to define a set of trusted Certificate Authority (CA) certificates that an application or system uses to verify the authenticity of SSL/TLS certificates presented by servers during secure communication. It serves as a trust anchor, allowing the application to establish the legitimacy of certificates in the trust chain presented by the server.
defaultContentType	string		`application/json`	Default content type the media types consumed by the operation (such as application/json). Request bodies are optional by default. JSON is 'application/json' XML is 'application/xml' Text is 'text/plain' FormData is 'application/x-www-form-urlencoded' Binary is 'multipart/form-data'.

Table: Rest parameters

Extended Parameters#

See Extended Data for the concept behind these protocol-specific attributes.

Command#

All Automation Commands defined in the Driver Definition that use this protocol will have the following extended (extra) attributes available to customize

Name	Type	Possible Values	Default Value	Description
requestMethod	Enum	`GET` `POST` `PUT` `DELETE` `PATCH`	`GET`	HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred to as HTTP verbs. Each of them implements a different semantic, but some common features are shared by a group of them: for example, a request method can be safe, idempotent, or cacheable.
timeout	Integer		`30000`	Timeout, in milliseconds, where the server fails to send any information.
successfulStatusCodes	String		`200`	HTTP response status codes indicate whether a specific HTTP request has been successfully completed. List of response status codes that can be accepted as success (use ',' as separator), for example '200,201,202'

Table: Rest specific extended command attributes

Command Parameter#

All Command Parameters defined in the Driver Definition that use this protocol will have the following extended (extra) attribute available to customize

Name	Type	Default Value	Description
operationParameters	Enum	`PathParameter`	Where this command parameter's value is placed on the HTTP request. See possible values below.

Table: Rest specific extended properties

Value	Description
`PathParameter`	Parameters passed via path (for example, `/users/:id`)
`QueryParameter`	Parameters placed after `?` in the URL (for example, `/users?role=Admin`)
`HeaderParameter`	Parameters sent in the request header (for example, `X-MyHeader: value`)
`RequestBody`	An object representing the request body (for example, `{ Id: 1, MaterialName: "Material01" }`)
`RequestBodyParameter`	Parameters used to build the request body. A `RequestBodyParameter` overrides a `RequestBody` value of the same name (for example, a `RequestBodyParameter` named `MaterialName` with value `Material02` would override `Material01` if the previous request body was defined)

Table: Possible values for operationParameters

Examples#

The examples below show how the extended data described above is set on a command of an Automation Driver Definition. Each command maps to one REST operation on the server, and each command parameter maps to one part of the request.

POST with a Request Body#

This command sends the whole content of its Body parameter as the JSON request body of a POST request to /MyPath/Endpoint, waits up to two minutes for the server, and accepts only 200 as success.

{
    "Name": "MyCommand",
    "Description": "Command Description",
    "DeviceCommandId": "/MyPath/Endpoint",
    "ExtendedData": {
        "requestMethod": "POST",
        "timeout": 120000,
        "successfulStatusCodes": "200"
    },
    "Parameters": [
        {
            "Name": "Body",
            "DataType": "Object",
            "AutomationProtocolDataType": "Object",
            "ExtendedData": {
                "operationParameters": "RequestBody"
            },
            "IsMandatory": true
        }
    ]
}

GET with a Path and a Query Parameter#

This command reads one material by identifier. The Id parameter replaces the :id placeholder in the path, and the role parameter is appended to the query string, so a call with Id set to 42 and role set to Admin requests /users/42?role=Admin.

{
    "Name": "GetUser",
    "Description": "Retrieve a user by its identifier",
    "DeviceCommandId": "/users/:id",
    "ExtendedData": {
        "requestMethod": "GET",
        "timeout": 30000,
        "successfulStatusCodes": "200,204"
    },
    "Parameters": [
        {
            "Name": "Id",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "PathParameter"
            },
            "IsMandatory": true
        },
        {
            "Name": "role",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "QueryParameter"
            },
            "IsMandatory": false
        }
    ]
}

PATCH Built from Individual Body Fields#

This command builds the whole request body from its individual parameters. Each RequestBodyParameter (MaterialName and MaterialState) becomes one field of the JSON body, and sends X-Correlation-Id as a request header.

{
    "Name": "UpdateMaterial",
    "Description": "Update the state of a material",
    "DeviceCommandId": "/materials/:id",
    "ExtendedData": {
        "requestMethod": "PATCH",
        "timeout": 30000,
        "successfulStatusCodes": "200,204"
    },
    "Parameters": [
        {
            "Name": "id",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "PathParameter"
            },
            "IsMandatory": true
        },
        {
            "Name": "MaterialName",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "RequestBodyParameter"
            },
            "IsMandatory": true
        },
        {
            "Name": "MaterialState",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "RequestBodyParameter"
            },
            "IsMandatory": false
        },
        {
            "Name": "X-Correlation-Id",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "HeaderParameter"
            },
            "IsMandatory": false
        }
    ]
}

Note

A RequestBodyParameter overrides a field of the same name in a RequestBody object, so you can send a base object and still override single fields from the workflow.

Downloading a File#

The driver reads the response according to its Content-Type header. It accepts JSON, XML, and any text/* response, and it fails with Unsupported Content Type for anything else.

Warning

The driver cannot retrieve a raw binary response, such as application/pdf, image/png, or application/octet-stream. Use an endpoint that returns the file as text, or one that returns it Base64-encoded inside a JSON response.

The driver also never writes to disk. It returns the content into the workflow, and a File Driver command can be used to write it. A download is therefore two commands:

The REST Client protocol to fetch the content.
The File protocol to write it.

Text File#

For a text response, such as a CSV or an XML report, the content arrives as a String.

{
    "Name": "DownloadReport",
    "Description": "Retrieve the daily report as CSV",
    "DeviceCommandId": "/reports/:reportId",
    "ExtendedData": {
        "requestMethod": "GET",
        "timeout": 60000,
        "successfulStatusCodes": "200"
    },
    "Parameters": [
        {
            "Name": "reportId",
            "DataType": "String",
            "AutomationProtocolDataType": "String",
            "ExtendedData": {
                "operationParameters": "PathParameter"
            },
            "IsMandatory": true
        }
    ]
}

In the workflow, connect the output of the Execute Equipment Command task that runs this command to the content parameter of a CreateFile command on the File driver:

{
    "Name": "WriteReport",
    "Description": "Write the retrieved report to disk",
    "DeviceCommandId": "WriteReport",
    "ExtendedData": {
        "commandType": "CreateFile"
    },
    "Parameters": [
        { "Name": "path", "DataType": "String", "AutomationProtocolDataType": "String", "IsMandatory": true },
        { "Name": "content", "DataType": "String", "AutomationProtocolDataType": "String", "IsMandatory": true }
    ]
}

Binary File Through a Base64 Response#

Many document APIs return a binary file as a Base64 string inside a JSON object, for example:

{
    "fileName": "certificate-4471.pdf",
    "content": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5ndGgg..."
}

The driver parses that response as JSON and returns it as an Object. Extract fileName and content with an Object Deserialize task, then write the file with a CreateFile command whose encoding parameter is set to base64, which decodes the string back to the original bytes:

{
    "Name": "WriteCertificate",
    "Description": "Write a Base64 payload to disk as a binary file",
    "DeviceCommandId": "WriteCertificate",
    "ExtendedData": {
        "commandType": "CreateFile"
    },
    "Parameters": [
        { "Name": "path", "DataType": "String", "AutomationProtocolDataType": "String", "IsMandatory": true },
        { "Name": "content", "DataType": "String", "AutomationProtocolDataType": "String", "IsMandatory": true },
        { "Name": "encoding", "DataType": "String", "AutomationProtocolDataType": "String", "IsMandatory": false }
    ]
}

Set encoding to base64 when the command is executed. Leaving it at the default of utf8 writes the Base64 text itself rather than the decoded file.

Note

The path parameter of a File driver command accepts the ${path}, ${archive}, ${temp}, and ${id} tokens, so a download can be written to the watched directory or to a temporary location without hardcoding it. See File Driver.

Remarks#

Connecting sends no request to the server, so the communication state does not show whether the server can be reached. An unreachable server shows only as a failed command.
When port is greater than 0, the driver writes it into every request URL, so an HTTPS server on its standard port needs port set to 443. With port set to 0, the driver adds no port.
The reply of a command holds the response body only. The status code and the response headers are not returned.