--- alias: user-guide-driver-restclient tags: - connect iot description: "This documentation details a Rest client for connecting to IoT devices" --- # 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](../index.md#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. ```json { "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`. ```json { "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. ```json { "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](driver_fileraw.md) 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. ```json { "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: ```json { "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: ```json { "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: ```json { "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](driver_fileraw.md). ## 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.