API Overview

The API is designed to be as RESTful as possible. The interfaces accept GET as well as POST requests to the endpoints.

Hardware / Sensor states

Get live data

curl http://host:5000/api/state/<name>

name has to be replaced with a name configured in config.yaml. Sensors return their current values converted to reasonable metric values. This means temperature is displayed in °C and humidity is displayed in %-rH.

curl http://host:5000/api/state[?FILTER=<regexp>&NAME_ONLY=<True/False>]

This returns all states. Param FILTER accepts any valid regex expression and param NAME_ONLY will flatten the array to just the names of the sensors. This is quite useful for the UI to client side request available sensors.

Switch hardware state

curl \
  -F "switch=<anyvalue>" \
  http://host:5000/api/state/<name>

name has to be replaced with a name configured in config.yaml. anyvalue can be set to whatever you like.

Set hardware state

curl \
  -F "state=<newstate>" \
  http://host:5000/api/state/<name>

name has to be replaced with a name configured in config.yaml. newstate can be set to change the sensor to the specified state.

For On it accepts true, yes, on, 1 (case insensitive) anything else is considered Off.

Request multiple states / or change them in one request

name can not only be filled with one name from config.yaml. It is also possible to provide multiple names separated by comma.

i.e. requesting multiple sensor outputs:

curl http://host:5000/api/state/SENSOR_TEMP,SENSOR_HUMID

i.e. switching multiple hardware actors to On state

curl \
  -F "switch=1" \
  http://host:5000/api/state/HEATING,UV

Data endpoint

Requesting sensor data for the last n-minutes

curl http://host:5000/api/data/<sensor>/<minutes>

As always sensor can be a comma separated list of sensors defined in config.yaml

Adding sensor data to database

I don't know (yet?) why this would be a good idea - but I wanted this endpoint to support post too.

curl \
  -F "value=<value>" \
  -F "timestamp=<epoch timestamp> \
  http://host:5000/api/data/<sensor>

This could be useful if you have external sensors maybe built on esp8266 you could aggregate data on this endpoint. As it would make no sense at all to submit the same datapoint to multiple sensors at once - this sensor does not support a comma separated list of sensors.

Graphs

This should yield a very responsive graph that can be embedded on almost any device at almost any resolution. The chart refreshes every 10 seconds.

Get graph

The endpoint /api/graphs/<sensor>/<minutes> returns HTML page with charts powered by chart.js. The sensor parameter takes a comma separated list of sensors to be rendered within the chart.

Set color of graphs

This endpoint accepts HTTP GET parameters to set the color of the lines (defaults to random colors).

curl http://host:5000/api/graphs/<sensor>/<minutes>?<sensor_name>=<color>&<sensor_name_n>=<color>&refresh=<refresh_miliseconds>

sensor_name has to match one of the sensor requested in sensor. color can be either (HTML color names)[https://www.w3schools.com/colors/colors_names.asp] or rgb(0-255,0-255,0-255) or rgba(0-255,0-255,0-255,0-1) or hsl(0-100%,0-100%,0-100%) or hex(#34ebae)