HTTP Server¶
Overview¶
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 the 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.
Permissions¶
User access and authentication can be configured using the existing connectware
functionalities for HTTP permissions, 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, e.g. data/cybustest/#
or
data/+/postRoute
.
Commissioning File Specifics¶
Custom Server Properties¶
basePath
(string)¶
Any additional base URL path in addition to the default /data/ base URL path
Default: ""
Examples: "/my/custom/path"
, "/"
requestMaxBodySize
(integer)¶
Default: 100000
Example: 100000
Additional restrictions:
Minimum:
1
Maximum:
512000
Custom Node Properties¶
method
(string, enum)¶
The HTTP method to be offered by this particular route node
This element must be one of the following enum values:
POST
PUT
route
(string)¶
The additional route path of this particular HTTP node, preceded by the server’s base url
Examples: "/my/individual/route"
, "/testroute"
Sending data to the HTTP Server¶
JSON¶
If the server receives a messages with the header
Content-type=application/json
, it will parse the HTTP message body in JSON
format, then transform the content into the internal message convention where
the message body is in the value
property. Example:
// Original message sent to HTTP server
{
"machineState": "okay",
"temperature": 23,
"logs": [
"message1",
"message2"
]
}
// Resulting protocol-mapper output at the MQTT broker
{
"timestamp": 12391238123, // milliseconds since epoch
"value": {
"machineState": "okay",
"temperature": 23,
"logs": [
"message1",
"message2"
]
}
}
If the request sent to the server is not parseable as JSON, it will be dropped and not forwarded 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 HTTP message body is forwarded to the specified topic without any further modification (no timestamp, no value property).
Sample Commissioning File¶
The endpoints from the commissioning file can be accessed using the following curl commands. It is assumed that the Connectware is configured so that the data route is accessible by 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://my.connectwareurl.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://my.connectwareurl.com/data/cybustest/putRoute' \
--header 'Authorization: Basic <BASIC AUTH TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"test2": "testdata send via PUT Route"
}'
Download: http-server-example.yml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | --- 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 httpMapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref postRoute publish: topic: output/postroute - subscribe: endpoint: !ref putRoute publish: topic: output/putroute |