HTTP acquisition API configuration#

Introduction#

Data acquisition via HTTP works by forwarding HTTP payloads from POST or PUT requests to the MQTT bus. The downstream infrastructure MQTTKit application will handle all the rest.

Setup#

This can be achieved by configuring a generic HTTP-to-MQTT forwarder application:

 1; ------------------------------------------
 2; Family:   Protocol forwarder
 3; About:    Versatile protocol forwarder components for bridging the gap between
 4;           different data sinks, bus systems and serialization formats.
 5; ------------------------------------------
 6; Name:     HTTP-to-MQTT protocol forwarder, generic
 7; About:    Suitable for data acquisition via HTTP POST/PUT requests.
 8; Channel:  Transport: HTTP, MQTT; Format: JSON, x-www-form-urlencoded
 9; See also: https://getkotori.org/docs/handbook/forwarders/http-to-mqtt.html
10;           https://getkotori.org/docs/handbook/acquisition/protocol/http.html
11; ------------------------------------------
12; Description:
13;
14;         - Listen to HTTP POST or PUT requests
15;         - Receive payloads formatted as JSON or in urlencoded format
16;         - Forward payloads to the MQTT bus
17;
18; Manual:   Please specify forwarding source and target parameters in URI format.
19;           The MQTT topic path is derived from the HTTP URI path by interpolating
20;           the appropriate part of the context URI.
21;
22; Example:  In the example below, given the "address" part of the resource URI
23;           is "testdrive/area-42/node-1", data sent to the full URI
24;
25;               /api/mqttkit-1/testdrive/area-42/node-1/data
26;
27;           will be republished to the MQTT topic
28;
29;               mqttkit-1/testdrive/area-42/node-1/data.json
30;
31; ------------------------------------------
32
33
34[mqttkit-1.http-api-generic]
35enable          = true
36
37type            = application
38application     = kotori.io.protocol.forwarder:boot
39
40realm           = mqttkit-1
41source          = http:/api/mqttkit-1/{address:.*}/{slot:(data|event)} [POST]
42target          = mqtt:/mqttkit-1/{address}/{slot}.json
43
44
45; ------------------------------------------------
46;   Notes about "source" and "target" parameters
47; ------------------------------------------------
48
49; Note that the "netloc" part (i.e. for specifying hostname/port)
50; in directives "source" and "target" are omitted from these uris.
51;
52; Kotori will only listen to the default HTTP port and forward
53; payloads to the default MQTT broker. Both are specified in the
54; main configuration file, usually "/etc/kotori/kotori.ini".
55;
56; However, this might change in the future to enable spinning
57; up HTTP listeners on arbitrary ports at runtime and to allow
58; publishing messages to different MQTT brokers.

Tip

Also have a look at HTTP for different ways to transmit telemetry data over HTTP.