HTTP export API configuration#

Introduction#

For enabling Data export via HTTP, just forward GET requests to the timeseries database, and let the transformation machinery handle all the rest.

Data export means access to raw data in different output formats as well as data plots.

Setup#

This can be achieved by configuring a generic 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 Export API forwarder
 7; Date:     June 2016
 8; About:    Suitable for data export from InfluxDB via HTTP GET requests.
 9; Channel:  Transport: HTTP
10; Format:   CSV, JSON, HDF5, NetCDF, matplotlib, ggplot,
11;           HTML, DataTables, dygraphs, Bokeh, Vega
12; See also: https://getkotori.org/docs/handbook/forwarders/http-api-export.html
13;           https://getkotori.org/docs/handbook/export/
14; ------------------------------------------
15; Description:
16;
17;         - Listen to HTTP GET requests
18;         - Transform inbound parameters to InfluxDB query expression
19;         - Query InfluxDB
20;         - Respond with raw data or data plots
21;
22; Manual:   Please specify forwarding source and target parameters in uri format.
23;
24;           In the example below, the quadruple (``realm / network / gateway / node``)
25;           will be transformed into::
26;
27;              database = {realm}_{network}
28;              series   = {gateway}_{node}
29;
30;           which will be used for querying InfluxDB. All identifiers are sanitized before.
31;
32;           Results from this query will get routed through a powerful
33;           data export machinery. The output format is determined
34;           by the ``suffix`` parameter.
35;
36; Example:  When requesting http://localhost:24642/api/mqttkit-1/testdrive/area-42/node-1/data.txt?from=2016-06-23&to=2016-06-27,
37;           the query expression against database "mqttkit_1_testdrive" will be::
38;
39;               SELECT * FROM area_42_node_1 WHERE time >= '2016-06-23 00:00:00.000' AND time <= '2016-06-27 23:59:59.999';
40;
41; ------------------------------------------
42
43[mqttkit-1.influx-data-export]
44enable          = true
45
46type            = application
47application     = kotori.io.protocol.forwarder:boot
48
49realm           = mqttkit-1
50source          = http:/api/{realm:mqttkit-1}/{network:.*}/{gateway:.*}/{node:.*}/{slot:(data|event)}.{suffix} [GET]
51target          = influxdb:/{database}?measurement={measurement}
52transform       = kotori.daq.strategy.wan:WanBusStrategy.topology_to_storage,
53                  kotori.io.protocol.influx:QueryTransformer.transform
54
55
56; ------------------------------------------------
57;   Notes about "source" and "target" parameters
58; ------------------------------------------------
59
60; Note that the "netloc" part (i.e. for specifying hostname/port)
61; in directives "source" and "target" are omitted from these uris.
62;
63; Kotori currently will only listen to the default http port
64; and query the default InfluxDB, both specified in the main
65; configuration file, usually "/etc/kotori/kotori.ini".
66;
67; However, this might change in the future to enable spinning
68; up HTTP listeners on arbitrary ports at runtime and to allow
69; querying data from different InfluxDB instances.