An API (Application Programming Interface) is a set of commands, functions, protocols, and objects that programmers can use to create software or interact with an external system. It provides developers with standard commands for performing common operations, so that code does not have to be written from scratch. (see https://www.talend.com/de/resources/was-ist-eine-api/ )
The VanPi OS has an HTTP API and an MQTT API, which can be used to communicate with the system from outside (and also internally).
HTTP API:
The HTTP API provides various endpoints that you can use to switch relays or dim dimmers, for example.
You can reach these endpoints at <RPI-IP>:1880/, so the Node-RED port must always be specified.
We use GET and PUT requests for this. We can get information via GET requests, and we use PUT requests to change states. For example, with a GET request to the endpoint /relay/2 we can see the current state of Relay 2 and the assigned name, and a PUT request to /relay/2/true would turn on the relay.
GET requests can simply be entered into the browser address field and you will then receive a response in JSON format.
To test the API in detail, we use the free program Postman ( https://www.postman.com ). This allows us to send all kinds of different requests to the system.
The API also makes it possible, among other things, to start the heating and set the desired temperature and a timer after which the heating switches off again.
You can find the HTTP API documented in more detail at https://pekaway.de/docs/communication/#http-api , or in the Node-RED backend in the “HTTP API” flow. A few endpoints have been added there that have not yet made their way into the documentation.
MQTT API:
Similar to the HTTP API, the whole thing also works via MQTT. For this we use different topics:
Under the topic “pkw/cmnd/…” we send requests, for example to switch relays, under “pkw/stat/…” we ask about the status, under “pkw/tele/…” we get the answer.
For testing purposes we use the free program MQTT-Explorer ( https://mqtt-explorer.com )
So, to switch our Relay 2, we send the payload “on” or “off” (alternatively “true” or “false” is also possible) to the topic “pkw/cmnd/relay/2/POWER”. This switches the relay accordingly.
There are also topics here to control the heating, for example. If we send the payload "on" to the topic "pkw/cmnd/heater/POWER/25/300", the heating is switched on, the desired temperature is set to 25 °C and the timer is set to 300 minutes, so the heating goes off again after 5 hours. The timers only run in the background for both APIs, you cannot see them.
The documentation for the MQTT API can be found at https://pekaway.de/docs/communication/#mqtt-api or again in the Node-RED backend in the “MQTT API” flow.
Tips and Tricks:
With the APIs you could write additional programs that run on another RPI or ESP, which in turn can access the data.
If you have programmed your own logic into our Node-RED flows, it is a good idea to write this logic in a separate flow and simply access the data internally via the APIs. This would provide a certain level of basic security in the event of an update, as you would only have to save this flow separately and can simply import it again later.
If you want to go one step further, you can install a second Node_RED instance on a different port. Then you can put your own logic there and access the data of the base instance from there via API.
DANGER: We access these APIs ourselves with various devices, for example the IoT Bridge and the Dimmy. So it's not us, but these devices... You know what I mean. In any case, that means that you shouldn't change these APIs. Of course, you can write your own endpoints etc. without any problems.
