HTTP Server/Node

Configure Connectware to expose data points over HTTP/REST using the HTTP Server and Node resources.

The HTTP Server resource offers access to data points through a HTTP/REST interface.

• This server will accept JSON data via POST or PUT and forwarding that data to corresponding MQTT topic.

• User access and authentication can be configured using the existing connectware functionalities for HTTP permissions.

• The listening port is the same port 443 which is also used for HTTPS access to the other REST interfaces of Connectware, where each request with the path /data refers to the internal HTTP server for data access.

The HTTP server can be configured using the Cybus::Server::Http resource. The server resource defines an optional base path prefix in addition to the standard /data prefix.

Each HTTP route is described by a Cybus::Node::Http resource that defines the path and http method as parameters to specify the route.

For configuration reference, see:

• HTTP Server Properties

• HTTP Node Properties

Permissions

Connectware controls access to HTTP endpoints using the existing role and permission system. For more information, see Roles and Permissions. For the example below where the user should PUT or POST to the route data/cybustest/postRoute, the user must be granted matching write permissions, for example data/cybustest/# or data/+/postRoute.

Sending Data to the HTTP Server

JSON

If the server receives a request with the Content-Type: application/json header, it parses the HTTP message body as JSON and wraps it in the value property of the internal message convention.

Example

// Original message sent to HTTP server
{
  "machineState": "okay",
  "temperature": 23,
  "logs": ["message1", "message2"]
}

The resulting output at the MQTT broker:

// Message received by MQTT broker
{
  "timestamp": 12391238123, // milliseconds since epoch
  "value": {
    "machineState": "okay",
    "temperature": 23,
    "logs": ["message1", "message2"]
  }
}

If the request body is not valid JSON, the server drops it and does not forward it to the MQTT broker.

Other Formats

Other supported MIME types in the Content-Type header are:

• application/octet-stream

• text/plain

• text/xml

• text/csv

In all of these cases, the server forwards the HTTP message body to the specified topic without further modification — no timestamp or value wrapping is applied.

Receiving Data from the HTTP Server

JSON

Each node with method: GET has an internal cache that stores the latest value written to it via the */write topic (depth of 1). The response is always a JSON object containing value and timestamp. If no timestamp is provided, one is generated. If no data is available, the server responds with HTTP 204.

For example, if the following message is published to the MQTT broker:

// Original message sent to MQTT broker
{
  "value": "Cybus"
}

Resulting protocol-mapper output at the MQTT broker

{
  "timestamp": 12391238123, // milliseconds since epoch
  "value": "Cybus"
}

Service Commissioning File Example

The endpoints from the service commissioning file can be accessed using the following curl commands. These assume Connectware is configured for basic auth authentication and that the user has sufficient HTTP permission to write to the path data/cybustest/postRoute.

The POST based demo endpoint:

curl --location --request POST 'https://example.com/data/cybustest/postRoute' \
--header 'Authorization: Basic ${BASIC_AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "test1": "testdata send via POST Route"
}'

The PUT based demo endpoint:

curl --location --request PUT 'https://example.com/data/cybustest/putRoute' \
--header 'Authorization: Basic ${BASIC_AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "test2": "testdata send via PUT Route"
}'

The GET based demo endpoint:

curl --location --request GET 'https://example.com/data/cybustest/getRoute' \
--header 'Authorization: Basic ${BASIC_AUTH_TOKEN}'

Replace ${BASIC_AUTH_TOKEN} with your base64-encoded credentials.

1KB

http-server-example.yml

Open

http-server-example.yml

---
description: Provides a demonstration structure for a http server configured in the protocol mapper

metadata:
  name: Definition By Example for HTTP Endpoints

parameters: {}

resources:
  httpServer:
    type: Cybus::Server::Http
    properties:
      basePath: /cybustest

  postRoute:
    type: Cybus::Node::Http
    properties:
      parent: !ref httpServer
      method: POST
      route: /postRoute

  putRoute:
    type: Cybus::Node::Http
    properties:
      parent: !ref httpServer
      method: PUT
      route: /putRoute

  getRoute:
    type: Cybus::Node::Http
    properties:
      parent: !ref httpServer
      method: GET
      route: /getRoute

  httpMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref postRoute
          publish:
            topic: output/postroute
        - subscribe:
            endpoint: !ref putRoute
          publish:
            topic: output/putroute
        - subscribe:
            topic: input/getRoute
          publish:
            endpoint: !ref getRoute