Rest API

Description

ezvpn-gw-rest is a service (provided as Docker container image) acting as a server Rest API.

Rest API Gateway Schema

ezvpn-gw-rest, is a container exposing a REST API allowing you to send messages to other containers, both local and remote, as long as they belong to the same network.

How to use it

ezvpn-gw-rest is a Docker container implementing an HTTP REST API.

You can define endpoints. Upon invocation of an endpoint, the associated action is executed.

Data can be sent to the endpoints as:

  • a raw string in the body of the POST request
  • a json payload in the body of the POST request
  • a value as a url positional parameter of the POST request
  • without any value

The possible actions are:

  • send a value to the internal MQTT broker
  • send a value to instances within the network

Listening port

8080 on http protocol. If the container is added from the catalog, the port 8080 is mapped to the port 8000 and by default you need to talk to the port 8000.

The default port mapping can be set to any other available port.

Container behavior

Only one environment variable must be provided: REST_CFG.

REST_CFG is a string representing a JSON object, describing the Rest API endpoints and their associated action.

The transport property shown below can have value:

  • mqtt: the action sends a message to the internal MQTT broker

  • network: the action sends a message to network instances

Example 1: send a value to the internal MQTT broker

The example below is sending the incoming JSON payload (posted to /sendToTest) to the topic test on the internal MQTT broker.

{
    "transport": "mqtt",
    "actions": [
        {
            "path": "/sendToTest",
            "body": "json",
            "destination": { "topic": "test" }
        }
    ]
}

Example 2: send a value to a network instance

The example below is sending the value 123 (posted to /setTemperature/123) to the remote instance named machine1, application named collector, protocol modbus, measurement setpoint.

{
    "transport": "network",
    "actions": [
        {
            "path": "/setTemperature",
            "destination": { 
                "target": "machine1/collector", 
                "protocol": "modbus", 
                "measure": "setpoint"
            }
        }
    ]
}

API Authentication

API calls are secured using a pre-shared API token. You have to pass the token as value of the X-Auth-Token header.

The authentication token is shown only at the first application startup. You can see it enabling the debug log in the management web site as in the picture below.

Rest API Auth

Lost token

If you forget the token, you must reset the application to the initial state, to generate a new token in the following way:

  1. Enter edit mode
  2. Execute one of the following procedures, at your convenience:
    1. procedure a
      1. remove the ezvpn-gw-rest container
      2. leave edit mode
      3. enter edit mode
      4. add again ezvpn-gw-rest
    2. procedure b
      1. remove the existing volume mapped to the /data folder
      2. leave edit mode
      3. enter edit mode
      4. add again the /data mapping
    3. procedure c
      1. using a file browser, remove /data/config.json
  3. Leave edit mode

Mapping configuration (REST_CFG)

The container configuration is a JSON with the following properties:

{
    "transport": <mqtt|network>,
    "actions": [<action 1>, <action 2>, ..., <action n>]
}
  • transport, Required:
    • mqtt if you need to send a value to the MQTT internal broker
    • network if you need to send a value to the IOhubTM network.

actions is an array of objects representing the endpoints and the associated message destination. The actions array cannot be empty.

In the action definition the <network destination> defined below:

  • is required if the transport is network. The format is defined here.

  • is absent if the transport is mqtt

Action can be one of the following types:

1) Action with JSON payload

{
    "path": "<endpoint>",
    "body": "json",
    "destination": {
        "target": "<network destination>",
        "topic": "<destination topic>"
    }
}

The endpoint must be invoked with POST method. The payload in the body is expected in JSON format; it is sent to the topic configured (optionally to the remote instance in case of network transport).

2) Action with raw payload

{
    "path": "<endpoint>",
    "body": "raw",
    "destination": {
        "target": "<network destination>",
        "topic": "<destination topic>"
    }
}

3) Action with value on url path

{
    "path": "<endpoint>",
    "destination": {
        "target": "<network destination>",
        "protocol": "<destination protocol>",
        "measure": "<destination measurement>"
    }
}

The endpoint must be invoked with POST method, adding /<value> to the endpoint. The value in the url is sent as a string value to the protocol and measurement configured (optionally to the remote instance in case of network transport).

E.g. post to /<endpoint>/123 to send the value 123.

4) Action with fixed value

{
    "path": "<endpoint>",
    "destination": {
        "target": "<network destination>",
        "protocol": "<destination protocol>",
        "measure": "<destination measurement>",
        "value": "<value to send>"
    }
}

The endpoint must be invoked with POST method. The value in the configuration is sent as a string value to the protocol and measurement configured (optionally to the remote instance in case of network transport).

Examples

Write a value to a setpoint measurement using modbus protocol

We want to write the value 265 to the Modbus PLC. Configure the Rest API container setting the REST_CFG environment variable as in the example below.

{
    "transport": "mqtt",
    "actions": [
        {
            "path": "/temp/setpoint/",
            "destination": {
                "protocol": "modbus", 
                "measure": "setpoint"
            }
        }
    ]
}

Using curl or any other HTTP client you can write the value to the PLC

curl -X POST -H "X-Auth-Token: <your token>" \
    http://<instance ip>:8000/temp/setpoint/265

Write a value to a setpoint measurement using modbus protocol in a remote PLC

We want to write the value 265 to a remote Modbus PLC modbus. We have an instance named plant123 along with an application named extruder. Configure the Rest API container setting the REST_CFG environment variable as in the example below.

{
    "transport": "network",
    "actions": [
        {
            "path": "/temp/setpoint/",
            "destination": {
                "target": "plant123/extruder",
                "protocol": "modbus", 
                "measure": "setpoint"
            }
        }
    ]
}

Using curl or any other HTTP client you can write the value to the PLC

curl -X POST -H "X-Auth-Token: <your auth token>" \
    http://<instance ip>:8000/temp/setpoint/265

Send a notification to slack

We want to sent a Slack notification using the Rest API container. Configure the Rest API container setting the REST_CFG environment variable as in the example below.

{
    "transport": "mqtt",
    "actions": [
        {
            "path": "/message/slack",
            "body": "raw",
            "destination": {
                "topic": "slack"
            }
        }
    ]
}

Using curl or any other HTTP client you can Send the message to the MQTT topic. The Slack container will process the message for you.

curl -X POST -H "X-Auth-Token: <your auth token>" \
    -d "This is a test message!" \
    http://<instance ip>:8000/message/slack

Environment variables

When you start the ezvpn-gw-rest image, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

General Configuration

  • REST_CFG: the url/action mapping definition. Required
  • HTTP_PORT: http listening port, defaults to 8080
  • DATA_FOLDER: permanent data folder for configuration. Defaults to /data

MQTT Connection

  • MQTT_HOST: MQTT host. Defaults to 127.0.0.1.
  • MQTT_PORT: MQTT port. Defaults to 1883.

Troubleshooting

  • Access to port 8000 is denied: if your hardware is configured in router mode, by default, access to any network port from WAN is denied. Read the section "Access from WAN" to unlock it.

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-gw-rest

Supported architecture: amd64

Changelog

v1.0.0
  • First release