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. Leave empty for all network addresses (0.0.0.0).
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.

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.
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).

Methods#

Register Event#

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

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

Example#

{
   "event":{
      "name": "CustomEvent",
      "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.

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

Example#

{
   "event":{
      "name": "CustomEvent"
   }
}

Execute Command#

Executes a custom command.

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

Example#

{
    "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": "StatusCode" }
        }
    ]
}