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` `HTTPS`	`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` `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: 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` `Query` `Header` `Body` `RequestId`	`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. Path parameters, such as /users/:id. Query parameters, such as /users?role=admin. Header parameters, such as { X-MyHeader: Value }. Body parameters from a JSON object such as { Quantity: 100 } (only possible if the body is in a JSON object format). 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. 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. 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` `Body` `HeaderParameter` `StatusCode`	`RequestId`	Type of the parameter to include in the reply. HeaderParameter: to set a specific parameter in the header section. StatusCode: Response code indicating the status of the request. Body: full content of the body in the accepted format/content-type. RequestId: to link the reply command to the respective request (mandatory).

Driver Extensions#

Deprecated

The extensibility mechanisms described in this section are deprecated and will be removed in a future version. Define custom properties, events, and commands at runtime with the Custom Driver Definition task (which calls driverProxy.registerCustomDriverDefinitions under the hood) instead.

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

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

Example

{
      "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

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

Example

{
   "name": "CustomEvent"
}

Execute Command#

Executes a custom command.

Signature

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

Example

{
    "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?.