Forwarder’s HTTP API

Forwarder can be configured via HTTP API on domain name: https://forwarder.energomonitor.com.

Authorization

HTTP Basic authorization. Username and password for accessing API will be provided upon request.

Resources

GET /config

Show existing configuration in JSON format.

POST /config

Configure forwarder for authorized customer. POST data should be formatted as JSON object with following keys:

  • interval: how ofter to forward all received data; number of minutes; allowed numbers are 1..60.

  • url: address where to forward data; should be fully qualified domain name with URL, for example https://api.example.com/data/from/homebases. The URL may contain user credentials, for example https://username:password@api.example.com/data/from/homebases. If present, the credentials are sent to the server in the Authorization header using the Basic HTTP authentication scheme.

  • format: data format; the only valid value is json.

  • mode: mode of operation, all will receive and send all data point without any further processing, aggregated will send aggregated results for the given time interval.

  • allow_list: allow datapoints to not be excluded based on medium or medium and index or obis or all together, can be omitted.

  • deny_list: exclude datapoints from forwarding based on medium or medium and index or obis or all together, can be ommited.

allow_list example:

"allow_list": [{”medium”:22, “index”: [1,2]}] or "allow_list": [{”obis”:"1-0:60.8.0*1"}] or "allow_list": [{”medium”:22, “index”: [1,2], ”obis”:"1-0:60.8.0*1"}] or "allow_list": [{”medium”:22, ”obis”:"1-0:60.8.0*1"}]

Notice: allow_list and deny_list cannot be filled both, only one of them can be used and index must be filled together with medium.

Supported modes

Forwarder supports two modes of operation. Mode all can be used when all data points from all Homebases/sensors are needed as they were generated. Please remember this mode can generate significant load on customers server. For example, one Homebase with two EOS6-OS (Optosense) sensors will send 180 measurements pers 15 minutes. One measurement contains 4 pairs medium/value, thus 720 data points from one Homebase per 15 minutes. For customers with 100 Homebases it means 6 MB JSON list will be sent to defined URL each 15 minutes.

The other supported mode is aggregated. When enabled, Forwarder aggregates all points associated with the same data stream into just one aggregated point. Data stream consists of all points with the same (gateway, channel, device, medium) tuple.

The way Forwarder aggregates particular data stream depends on the medium. In general there are 3 ways how to aggregate:

  • LAST: The last data point is picked. Used e.g. for counters.

  • AVERAGE: The average value is computed and returned. Used e.g. for temperature.

  • INTEGRAL: Computing integral for the given time interval. Integral aggregation is not available at the moment. Used e.g. for converting watts into watt-hours.

The aggregated point’s timestamp is set to the end of the given time interval. Moreover, when INTEGRAL is used, the aggregated point’s medium is changed as well:

  • Medium 1 becomes 22.

  • Medium 12 becomes 22.

  • Medium 13 becomes 23.

  • Medium 14 becomes 24.

  • Medium 18 becomes 28.

Example: send all data in JSON format every 15 minutes to address https://api.example.com/data.

interval = 15
url = "https://api.example.com/data"
format = "json"
mode = "all"

Sending data

Forwarder sends data periodically according to selected mode and time interval. It uses at-least-once semantics, meaning that when it is not sure whether the data has been successfuly delivered (e.g. in case of a network error), it will try to deliver it again.

Forwarder’s behavior also depends on status code returned by customer’s endpoint:

  • 2xx: Success. Forwarder will continue with sending the next request.

  • 1xx, 3xx, 5xx: Assuming temporary server failure. Forwarder will retry sending the same request until the endpoint returns a 2xx or 4xx status code.

  • 4xx: Assuming permanent client failure. Forwarder will drop the current request and will continue with sending the next request.

There is also a delay between registering/unregistering a Homebase and starting/stopping sending its data. As a result, Forwarder may occasionally attempt to send data from a Homebase that is not currently registered (it has been recently unregistered).

What all this means for customer’s endpoint?

  • It should be ready to receive duplicate data. The correct action in this case is to drop the data and return a 2xx.

  • It should be ready to receive data from a gateway that is not currently registered. The correct action in this case is to drop the data and return a 2xx.

  • It should be careful with 4xx status codes. It sholud return a 4xx only in case of errors that make the data unreadable (e.g. invalid JSON, missing data items, invalid data item types). Returning it in other circumstances may lead to data loss.

Postel’s law applies here:

Be conservative in what you send, be liberal in what you accept.

GET /register

List all registered serial numbers.

POST /register/{sn}

Register Homebase with given serial number ({sn} in URL, 16 characters, [0-9A-F]{16}). Each Homebase has to be registered before forwarder starts to receive and send its data.

POST data for this endpoint are empty. Any payload will be ignored.

Note: Homebase registered to forwarder cannot be used in standard Energomonitor app.

DELETE /register/{sn}

Unregister Homebase with given serial number. After Homebase is unregistered the forwarder stops receive and send its data.

Note: as soon as Homebase is unregistered from forwarder it can be used in Energomonitor application again.