LogoLogo
Contact Uscybus.io
Connectware 1.11.0
Connectware 1.11.0
  • Getting Started
    • Introduction
    • System Requirements
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Installation and Upgrades
      • Installing Connectware
        • Installing Connectware (Kubernetes)
        • Installing Connectware (Docker)
      • Upgrading Connectware
        • Upgrading Connectware (Kubernetes)
          • Version-Specific Upgrades (Kubernetes)
        • Upgrading Connectware (Docker)
          • Version-Specific Upgrades (Docker)
      • Uninstalling Connectware
        • Uninstalling Connectware (Kubernetes)
        • Uninstalling Connectware (Docker)
      • Licensing
      • Restarting Connectware
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Single Sign-On (SS0)
        • Single Sign-On with Microsoft Entra ID
        • Single Sign-On with LDAP
      • JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
    • Services
      • Service Overview
      • Service Resources View
        • Service Links View
        • Servers View
        • Containers View
        • Volumes View
        • Connections View
        • Endpoints View
        • Mappings View
      • Service Details View
      • Service Commissioning Files
        • Version
        • Description
        • Metadata
        • Parameters
        • Definitions
        • Resources
          • Cybus::Connection
          • Cybus::Container
            • Docker Problem with Network Changes
          • Cybus::Endpoint
          • Cybus::File
          • Cybus::IngressRoute
          • Cybus::Link
          • Cybus:Mapping
          • Cybus::Node
          • Cybus::Role
          • Cybus::Server
          • Cybus::User
          • Cybus::Volume
      • Setting Up and Configuring Services
        • Installing Services
        • Enabling Services
        • Updating Services
        • Disabling Services
        • Deleting Services
      • FlowSync
        • Example 1 - Node with Transaction Mode (HTTP)
        • Example 2 - Node Responds (HTTP)
        • Example 3 - Node with Error (HTTP)
        • Example 4 - Node with Timeout Error Code and Error Message (HTTP)
        • Example 5 - Full Transactional Data Flow (HTTP)
        • Example 6 - Full Transactional Data Flow (OPC UA)
      • ServiceID
      • Inter-Service Referencing
      • Deviations
      • Service Logs
        • Logs of Individual Services
        • Logs of All Services
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • Shared Subscriptions
        • Setting Up Shared Subscriptions
    • Agents
      • Agents View
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Agents in Kubernetes
        • Adding Agents Inside your Connectware Installation
        • Remote Agents with the connectware-agent Helm Chart
        • Kubernetes Cluster Requirements for the connectware-agent Helm Chart
        • Installing Connectware Agents using the connectware-agent Helm Chart
        • Installing Connectware Agents without a License Key Using the connectware-agent Helm Chart
        • Upgrading the connectware-agent Helm Chart
        • Uninstalling Connectware agents with the connectware-agent Helm chart
        • Configuration Principles for the connectware-agent Helm Chart
        • Configuring Agents with the connectware-agent Helm Chart
          • Configuring Target Connectware for the connectware-agent Helm Chart
          • Configuring Agent Persistence for the connectware-agent Helm Chart
          • Configuring Compute Resources for the connectware-agent Helm Chart
          • Using a Custom Image Registry for the connectware-agent Helm Chart
          • Configuring Image Pull Policy for the connectware-agent Helm Chart
          • Using Mutual Transport Layer Security (mTLS) for agents with the connectware-agent Helm chart
          • Configuring image name and version for the connectware-agent Helm chart
          • Configuring Environment Variables for the connectware-agent Helm Chart
          • Configuring Labels and Annotations for the connectware-agent Helm Chart
          • Configuring podAntiAffinity for the connectware-agent Helm Chart
          • Assigning Agents to Kubernetes Nodes for the connectware-agent Helm Chart
          • Configuring Security Context for the connectware-agent Helm Chart
          • Controlling the Name of Kubernetes Objects for the connectware-agent Helm Chart
      • Troubleshooting Agents
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
    • Certificates
      • Certificates View
      • Adding Certificates
      • Removing Certificates
    • Monitoring
      • Data Explorer
      • Live Data
    • Node-RED Workbench
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
    • Backup and Restore
      • Volumes
      • User Database
    • CybusMQ
      • Configuring CybusMQ
    • Connectware on Kubernetes
      • Connectware Helm Chart
      • Resizing Broker Volumes in Kubernetes
      • Configuring Core Services
      • LDAP Authentication
        • Configuring LDAP Authentication
        • Enabling TLS for LDAP Authentication
        • Manual Kubernetes Secret for LDAP Authentication Bind User
        • Customizing the Search Filter for LDAP Authentication
        • Customizing the User RDN for LDAP Authentication
      • Troubleshooting Connectware on Kubernetes
    • Environment Variables
    • Industry Protocol Details
      • ADS
        • ADS Connection Properties
        • ADS Endpoint Properties
      • BACnet
        • BACnet Connection Properties
        • BACnet Endpoint Properties
      • Custom Connectors
        • Developing Custom Connectors
        • Deploying Custom Connectors
        • Using Custom Connectors
      • EtherNet/IP
        • EtherNet/Ip Connection Properties
        • EtherNet/Ip Endpoint Properties
      • FOCAS
        • FOCAS Connection Properties
        • FOCAS Endpoint Properties
      • Hottinger Baldwin Messtechnik (HBM)
        • HBM Connection Properties
        • HBM Endpoint Properties
      • Heidenhain DNC
        • Heidenhain DNC Connection Properties
        • Heidenhain DNC Endpoint Properties
      • HTTP/REST
        • HTTP/REST Connection Properties
        • HTTP/REST Endpoint Properties
      • HTTP Server/Node
        • HTTP Server Properties
        • HTTP Node Properties
      • InfluxDB
        • InfluxDB Connection Properties
        • InfluxDB Endpoint Properties
      • Kafka
        • Kafka Connection Properties
        • Kafka Endpoint Properties
      • Modbus/TCP
        • Modbus/TCP Connection Properties
        • Modbus/TCP Endpoint Properties
      • MQTT
        • MQTT Connection Properties
        • MQTT Endpoint Properties
      • MSSQL
        • Mssql Connection Properties
        • Mssql Endpoint Properties
      • OPC DA
        • OPC DA Connection Properties
        • OPC DA Endpoint Properties
      • OPC UA
        • OPC UA Client
          • OPC UA Client Connection Properties
          • OPC UA Client Endpoint Properties
        • OPC UA Server
          • OPC UA Server Properties
          • OPC UA Node Properties
        • OPC UA Object Types
        • OPC UA Server References
          • OPC UA Reference Node
          • OPC UA Object Node
      • Siemens SIMATIC S7
        • Siemens S7 Connection Properties
        • Siemens S7 Endpoint Properties
      • Shdr
        • Shdr Connection Properties
        • Shdr Endpoint Properties
      • SINUMERIK
        • SINUMERIK Connection Properties
        • SINUMERIK Endpoint Properties
      • SOPAS
        • SOPAS Connection Properties
        • SOPAS Endpoint Properties
      • SQL
        • SQL Connection Properties
        • SQL Endpoint Properties
      • Werma WIN Ethernet
        • Werma WIN Ethernet Connection Properties
        • Werma WIN Ethernet Endpoint Properties
      • Systemstate
        • Systemstate Endpoint Properties
    • API Reference
      • User Management (API)
      • Client Registry (API)
      • Services (API)
      • Resources (API)
      • System Status (API)
      • Resource Status Tracking (HTTP API)
      • Industry Protocol Details (API)
    • Changelog
Powered by GitBook
On this page
  • Commissioning File Specifics
  • Subscribing Data from a REST Server
  • Reading Data from a REST Server
  • Publishing Data to a REST Server
  • Connection Probing
  • Oauth 2.0 Client Credentials Grant
  • Service Commissioning File Example

Was this helpful?

  1. Documentation
  2. Industry Protocol Details

HTTP/REST

PreviousHeidenhain DNC Endpoint PropertiesNextHTTP/REST Connection Properties

Last updated 2 months ago

Was this helpful?

LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

The HTTP/REST Module is suitable for either of the following methods:

  • manual polling of endpoints (read)

  • continuous polling of endpoints (subscribe)

  • publishing data to endpoints (write)

The HTTP server to be contacted is described by the Cybus::Connection resource. This resource defines hostname, scheme, port, but also additional headers or authentication info. Each REST endpoint is described by a Cybus::Endpoint resource (no pun intended) that defines access to a particular REST path, optionally specifying additional query parameters or headers for this REST path.

The currently supported authentication methods are

  • Username/password for a basicAuth scheme

  • Arbitrary header for e.g. literal Bearer Tokens

  • Oauth 2.0 Client Credentials Grant

Commissioning File Specifics

The Endpoints for the HTTP connections may either use subscribe for subscribing, read for event-driven polling, or write for publishing, as described above.

Subscribing Data from a REST Server

When subscribing, the REST Server is polled at regular intervals according to the interval property of the endpoint resource. Each endpoint must contain a path and may contain additional header and query parameters.

If the request fails, a warning is logged but no action is taken.

Polling is implemented with a best-effort strategy, which means polling will take place at best with the desired interval. If the REST server response takes longer than the polling interval, the next request will not be triggered before the previous has been completed. This prevents building up of infinite queues in the event of unfortunate response time / polling interval combinations. However, this serialization is implemented per endpoint (per REST path), so that multiple requests to different paths can actually be in-flight in parallel.

Response Message

Similar to most protocol implementations in the Cybus Connectware, the server response will be wrapped in a JSON structure that follow the convention timestamp/value, like so:

{ 'timestamp': 12391238123, ? // ms since epoch
      "value"
    : ...              // server response }

If the server responds with a Content-type=application/json, the response JSON will be embedded to this object as value of the "value" property, like so:

// Original server response
{
  "machineState": "okay",
  "temperature": 23,
  "logs": [
    "message1",
    "message2"
  ]
}

// Resulting protocol module output at MQTT broker
{
   "timestamp": 12391238123, // ms since epoch
   "value": {
      "machineState": "okay",
      "temperature": 23,
      "logs": [
        "message1",
        "message2"
      ]
    }
}

If the server response is not parseable as JSON, it will be embedded into the message object as a string, hence

// Original server response
<?xml><root><some interesting="other">protocol</some></root>

// Resulting protocol module output to Cybus broker
{
   "timestamp": 12391238123, // ms since epoch
   "value": "<?xml><root><some interesting="other">protocol</some></root>"
}

Reading Data from a REST Server

The message sent on the endpoint’s /req topic does not need to have any content to trigger reading of data.

Dynamic path

If the REST endpoint to be called requires a dynamic (changing) path, the configured path property can be overwritten by the message to the endpoint. This is done by providing a path property string in the message payload.

Example message with dynamic path overwriting (to be sent on the /req topic):

{ 'path': '/bar' }
# Configured path: /foo
# Actual path    : /bar

It is also possible to append some path suffix to the configured path property by the message to the endpoint. Appending requires providing a pathAppend property string in the message payload.

Example message with dynamic path appended using pathAppend (to be sent on the /req topic):

{ 'pathAppend': '/bar' }
# Configured path: /foo
# Actual path    : /foo/bar

Dynamic query parameters

If the REST endpoint to be called requires dynamic query parameters, these can be provided in the message payload as key-value pairs.

Example message with dynamic query parameters (to be sent on the /req topic):

{ 'query': { 'foo': 'bar', 'user': 'cybus' } }

If the endpoint’s configuration already has a query property, both provided query parameters are merged. If any parameters are duplicated, the dynamic parameters from the message payload override the ones from the static configuration.

Publishing Data to a REST Server

The HTTP/REST Protocol Mapper also supports the other direction of data flow, namely publishing (pushing) data from MQTT to a REST server using the write property in the Cybus::Endpoint resource. Publishing does not work on a regular time interval but will directly forward any new message that is received from the broker on the /set topic of the endpoint.

The data of the internal MQTT message must be of type object and has to contain a property called body, which will be forwarded as the body of the HTTP request.

{ 'body': { 'foo': 'bar' } }

The request mime type header of the outgoing HTTP request will be set according to the internal MQTT message value: If the message contains parseable JSON, the mime type of the HTTP request will be set to application/json, otherwise it will be set to application/octet-stream. Besides that, no further changes are performed on the request. Any additional headers as defined in the endpoint resource will be passed on as given.

{ 'id': 29194, 'timestamp': 1629351968526, 'result': { 'value': 0 } }

In this result message, id is the request identifier that was sent on the original request, timestamp is the Unix timestamp of when the result was received, and result is the JSON object with the actual result, but its content depends on the concrete protocol implementation.

If there was an error, the resulting JSON object does not contain a property result but instead a property error. This property is simply a string variable and contains an explanatory message of the error. Hence, in the error case the data message on the result topic will have the following format:

{ 'id': 29194, 'timestamp': 1629351968526, 'error': 'POST request on /foo/bar failed with status: 403 Forbidden' }

Dynamic path

If the REST endpoint to be called requires a dynamic (changing) path, the configured path property can be overwritten by the message to the endpoint. This is done by providing a path property string in the message payload.

Example message with dynamic path overwriting (to be sent on the /set topic):

{ 'path': '/bar', 'body': { 'baz': 'qux' } }
# Configured path: /foo
# Actual path    : /bar

It is also possible to append some path suffix to the configured path property by the message to the endpoint. Appending requires providing a pathAppend property string in the message payload.

Example message with dynamic path appended using pathAppend (to be sent on the /set topic):

{ 'pathAppend': '/bar', 'body': { 'baz': 'qux' } }
# Configured path: /foo
# Actual path    : /foo/bar

Encoded request body

{ 'bufferFromBody': 'base64', 'body': 'YmFy' }

Connection Probing

While HTTP by itself doesn’t require a continuous connection, the HTTP protocol implementation in the Connectware is monitoring the connection state for up-to-date connectivity information. The connection state is estimated by monitoring each successful read and write, and additionally by a probing function scheduled to run if no read or write operation is in progress. The additional probing function is run after the time interval from the property probeInterval (default: 10 seconds).

By default the probing is performed by sending an OPTIONS request against the endpoint server. If this request fails with network error (e.g. ECONNRESET, ETIMEOUT, EUNREACHABLE), the connection state is assumed to be disconnected. If it succeeds, or if it at least gets a HTTP response from the endpoint, the connection is assumed to be connected.

Additionally the properties probePath and probeMethod allow configuring a custom HTTP path and HTTP method to be used by the probing function. See the section Connection Properties for more details on these properties.

Oauth 2.0 Client Credentials Grant

Tokens are automatically refreshed when they expire.

To use this authentication method the property oauthClientCredentials needs to be configured in the connection object providing client_id, client_secret, auth_url and, optionally, as some Oauth 2.0 implementations do not require it, audience and grant_type (which defaults to client_credentials).

Example configuration:

httpConnection:
    type: Cybus::Connection
    properties:
        protocol: Http
        targetState: connected
        connection:
            scheme: https
            host: one.host.io
            oauthClientCredentials:
                client_id: your_client_id
                client_secret: your_client_secret
                auth_url: oauth2.token.server

Service Commissioning File Example

http-example.yml
---
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Copyright: Cybus GmbH (2020)
# Contact: support@cybus.io
# ----------------------------------------------------------------------------#
# Source Interface Definition - HTTP/REST endpoint
# ----------------------------------------------------------------------------#

description: >
    Sample commissioning file for communicating with HTTP/REST endpoint

metadata:
    name: Http Connectivity
    icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
    provider: cybus
    homepage: https://www.cybus.io
    version: 0.0.1

parameters:
    httpHost:
        description: IP address of the HTTP Server
        type: string
        default: 192.168.0.1

    httpPort:
        description: HTTP port of the Server
        type: number
        default: 80

    initialReconnectDelay:
        type: integer
        default: 1000

    maxReconnectDelay:
        type: integer
        default: 30000

    factorReconnectDelay:
        type: integer
        default: 2

resources:
    httpConnection:
        type: Cybus::Connection
        properties:
            protocol: Http
            connection:
                scheme: https
                host: !ref httpHost
                port: !ref httpPort
                connectionStrategy:
                    initialDelay: !ref initialReconnectDelay
                    maxDelay: !ref maxReconnectDelay
                    incrementFactor: !ref factorReconnectDelay

    base:
        type: Cybus::Endpoint
        properties:
            protocol: Http
            connection: !ref httpConnection
            subscribe:
                path: /

    counter:
        type: Cybus::Endpoint
        properties:
            protocol: Http
            connection: !ref httpConnection
            subscribe:
                path: /counter

    getPost:
        type: Cybus::Endpoint
        properties:
            protocol: Http
            connection: !ref httpConnection
            subscribe:
                path: /post

    writePost:
        type: Cybus::Endpoint
        properties:
            protocol: Http
            connection: !ref httpConnection
            write:
                path: /post

    httpMapping:
        type: Cybus::Mapping
        properties:
            mappings:
                - subscribe:
                      endpoint: !ref base
                  publish:
                      topic: !sub '${Cybus::MqttRoot}/server/base'
                - subscribe:
                      endpoint: !ref counter
                  publish:
                      topic: !sub '${Cybus::MqttRoot}/server/counter'
                - subscribe:
                      endpoint: !ref getPost
                  publish:
                      topic: !sub '${Cybus::MqttRoot}/server/post'
                - subscribe:
                      endpoint: !ref counter
                  publish:
                      endpoint: !ref writePost

Data can also be read from the server on certain events. Reading data from the server is triggered by sending a message to the /req topic of the endpoint (see also ). The response from the server is written to the /res topic of the endpoint.

The result of the HTTP request is returned on the /res topic of the endpoint, as explained here: . The data message on the result topic will have the following format:

If it is required to send binary data as the request body, it is possible to specify the encoding of the message payload body parameter using a flag called bufferFromBody. The contend of the body parameter will then be converted into a buffer, respecting the encoding. Allowed encodings can be found here .

This module supports the Oauth 2.0 Client Credentials Grant flow for authenticating requests (see ).

Connection Properties
Endpoint Properties
https://nodejs.org/api/buffer.html#buffers-and-character-encodings
rfc6749 Section-4.4
Operation results
Operation results
3KB
http-example.yml