---
alias: user-guide-driver-restserver
tags:
- connect iot
description: "This documentation details a REST server for IoT data exchange, offering configurable communication protocols and data handling"
---

# Connect IoT - Rest Server

This server allows connection and exchange of data using stateless communication with a REST client. It provides resources and services via standard HTTP methods (GET, POST, PUT, DELETE and PATCH). The server processes client requests, interacts with underlying data sources, and returns appropriate responses.

## Data Types

These are the supported specific data types:

Name        | Description
------------|-------------------------
String      | String value
Boolean     | Boolean value
Integer     | Integer value
Decimal     | Decimal value
DateTime    | DateTime value
Object      | Structured 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
--------------------     | ------- | --------------- | ------------- | ------------
address                  | String  |                 | `0.0.0.0`     | Address (Ip) to listen to. Use `0.0.0.0` for all network addresses. When empty, the server listens on `127.0.0.1` only.
port                     | Integer |                 |  `80`         | Port number the server will be listening. Defaults to 80.
protocol                 | Enum    | `HTTP`<br/>`HTTPS`<br/> |  `HTTP`  | The protocol used for exchanging data.
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.
certificate              | Text    |    | "" | Own server certificate - can be either a path to a file or the contents of the file in plain text. Format should be 'pem'.
key                      | Text    |    | "" | Own server private key - can be either a path to a file or the contents of the file in plain text. Format should be 'pem'.


Table: Rest parameters

## Extended Parameters

### Event

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

The Event's `deviceId` is its **Endpoint Path** (e.g. `/api/trackIn/:id`). A route segment such as `:id` acts as a token: it can be resolved by an Automation Property whose `requestComponentType` is set to `Path` and whose `deviceId` matches the token name (`id`).

| Name         | Type | Possible Values                            | Default Value  | Description                                                  |
| ------------ | ---- | ------------------------------------------ | -------------- | ------------------------------------------------------------ |
| requestMethod | Enum | `GET`<br>`POST`<br>`PUT`<br>`DELETE`<br>`PATCH`<br> | `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: e.g. a request method can be safe, idempotent, or cacheable. |
| automaticReply | Boolean |  | `true` | Automatically send a reply to the request with the default code defined in the Automatic Reply Status Code setting. |
| automaticReplyStatusCode | Integer |  | `200` | To define the StatusCode if the Automatic Reply is set to true. |
| timeout | Integer |  | `60000` | Timeout, in milliseconds, where the server fails to send a reply to the request (Automatic Reply = false).

### Automation Property

All **Automation Properties** 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                                                  |
| ------------ | ---- | ------------------------------------------ | -------------- | ------------------------------------------------------------ |
| requestComponentType | Enum | `Path`<br>`Query`<br>`Header`<br>`Body`<br>`RequestId`<br> | `Path` | On a request received from a client, this configuration refers to the part of the message where the property value should be resolved from.<br>Path parameters, such as /users/:id.<br>Query parameters, such as /users?role=admin.<br>Header parameters, such as { X-MyHeader: Value }.<br>Body parameters from a JSON object such as { Quantity: 100 } (only possible if the body is in a JSON object format).<br>Note: The RequestId is a mandatory property, as it is used to emit the id of the message that will be used on the reply command.<br>Path parameters are resolved from the route definition (for example /users/:id/:name). The property deviceId must match the parameter name (id, name). When fullContent is false, the resolved value is the single parameter value; when fullContent is true, the resolved value is the full params object.
| fullContent | Boolean |  | `false` | To retrieve the full content of the specified RequestComponentType.<br>Note: The request body, only allows to retrieve a specific parameter if the content type is JSON. |

### Command Parameter

All **Command Parameters** 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                                                  |
| ------------ | ---- | ------------------------------------------ | -------------- | ------------------------------------------------------------ |
| replyParameterType | Enum | `RequestId`<br>`Body`<br>`HeaderParameter`<br>`StatusCode` | `RequestId` | Type of the parameter to include in the reply.<br>HeaderParameter: to set a specific parameter in the header section.<br>StatusCode: Response code indicating the status of the request.<br>Body: full content of the body in the accepted format/content-type.<br>RequestId: to link the reply command to the respective request (mandatory). |

## Driver Extensions

{% include-markdown 'includes/pages/iot_driver_extensions_deprecated.md' %}

This protocol driver provides a set of extension that allow the customization to perform actions that are independent of the Driver Definitions associated. This means you can, using customization, register events that are not present in the Driver Definition.

> This is particularly useful when accessing equipment data that is shared/too complex to access using the regular mechanisms. Also useful when needing to access data whose naming convention may vary from device to device.

### Objects

The objects are structures that are either passed as parameters or returned as result values.

#### Event

| Name       | Type         | Description                                                         |
| ---------- | ------------ | ------------------------------------------------------------------- |
| name       | String       | Name of the event. Will be used as identifier in the result calls.  |
| deviceId   | String       | Endpoint path of the event, for example `/api/batchStage`.          |
| isEnabled  | Boolean      | Is the event enabled and ready to be used? Default `true`           |
| properties | `Property`[] | List of properties to link with the event                           |

#### Property

| Name         | Type        | Description                                                                                         |
| ------------ | ----------- | --------------------------------------------------------------------------------------------------- |
| name         | String      | Name of the property. Will be used as identifier in the result calls.                               |
| deviceId     | String      | Identifier of the property in the request (e.g. path/header/body key or `requestId`).               |
| deviceType   | String      | Data type as known by the protocol. Must use one from the supported Data Types of this driver.      |
| dataType     | String      | Data Type of the value as known/used by the MES/System.                                             |
| extendedData | Json object | Extended Property attributes such as `requestComponentType` and `fullContent`.                      |

#### ExecuteCommand

| Name       | Type           | Description                                                  |
| ---------- | -------------- | ------------------------------------------------------------ |
| command    | Object         | Command to execute, with `name`, `deviceId`, and `parameters`, each parameter with its `replyParameterType` extended data. |
| parameters | Object         | Value of each command parameter, by parameter name.          |

### Methods

#### Register Event

Notifies the protocol driver to raise the occurrences of a specific event when it occurs.

**Signature**

```ts
void connect.iot.driver.template.registerEvent(data: Event)
```

**Example**

``` json
{
      "name": "CustomEvent",
      "deviceId": "/api/batchStage",
      "isEnabled": true,
      "properties":[
            {
                "name":"batchStage",
                "deviceId":"batchStage",
                "dataType":"Object",
                "deviceType":"Object",
                "extendedData":{ 
                    "requestComponentType": "Body",
                    "fullContent": true
                }
            },
            {
                "name":"requestId",
                "deviceId":"requestId",
                "dataType":"String",
                "deviceType":"String",
                "extendedData":{ 
                    "requestComponentType": "RequestId",
                    "fullContent": false
                }
            }
      ]
}
```

#### Unregister Event

Notifies the protocol driver to stop raising the occurrences of a specific event when it occurs.

**Signature**

```ts
void connect.iot.driver.template.unregisterEvent(data: Event)
```

**Example**

```json
{
   "name": "CustomEvent"
}
```

#### Execute Command

Executes a custom command.

**Signature**

```ts
any connect.iot.driver.template.executeCommand(data: ExecuteCommand)
```

**Example**

```json
{
    "command": {
        "deviceId": "CustomCommand",
        "name": "CustomCommand",
        "parameters": [
            {
                "name": "requestId",
                "deviceId": "RequestId",
                "dataType": "String",
                "deviceType": "String" ,
                "extendedData": { "replyParameterType": "RequestId" }
            },
            {
                "name": "statusCode",
                "deviceId": "StatusCode",
                "dataType": "Integer",
                "deviceType": "Integer" ,
                "extendedData": { "replyParameterType": "StatusCode" }
            },
            {
                "name": "body",
                "deviceId": "Body",
                "dataType": "Object",
                "deviceType": "Object" ,
                "extendedData": { "replyParameterType": "Body" }
            }
        ]
    },
    "parameters": {
        "requestId": "6c1f0e2a-4b7d-4f3e-9a51-2d8c7b9e0f13",
        "statusCode": 200,
        "body": { "accepted": true }
    }
}
```

## Remarks

- The server listens from the moment the driver connects, and adds the routes of the enabled events when the setup completes. A request that arrives before then is answered `404`.
- The driver package includes the command template *Request Reply Command* (`RequestReplyCommand`), with the parameters `RequestId` (`replyParameterType` `RequestId`), `StatusCode` (`StatusCode`, default value `200`), and `Body` (`Body`).
- When `automaticReply` is `false` and no reply is sent within the event's `timeout`, the client is answered `500` with `Timeout occurred while waiting for a reply to your request!`. A reply sent after that fails with `Unable to find a pending request with id '<id>'. Maybe it timed out?`.