REST API¶

Die REST-API ist die primäre Schnittstelle zwischen den Oberflächen und dem Backend. Während die Geräte selbst über MQTT angebunden sind, kommuniziert das Web-Dashboard und die Mobile App über HTTP mit der Plattform: Sie fragen Geräte und Telemetrie ab, senden Befehle und verwalten Automationsregeln. Für Live-Aktualisierungen ohne Polling ergänzt die WebSocket-Schnittstelle die REST-API.

Authentifizierung¶

Damit keine unbefugten Anfragen das System erreichen sind alle schreibenden POST-Endpunkte über einen API-Key geschützt. Somit können nur offizielle Frontends wie die Website und Apps Commands an Geräte senden.

Geräte¶

Die Geräte-Endpunkte liefern die registrierten Geräte inklusive ihres aktuellen Verbindungsstatus. Mit einzelnen UUIDs lassen sich auch die vollständigen Thing Models abrufen. Dies ist der zentrale Einstiegspunkt für Oberflächen um die registrierten Geräte nachzuschlagen sowie ausgewählte in die Oberfläche anzuzeigen.

Methode & Pfad	Beschreibung
`GET /devices`	Liste aller registrierten Geräte
`POST /devices/batch`	Mehrere Geräte in einer Anfrage abrufen
`GET /devices/:uuid`	Einzelnes Gerät inklusive vollständigem Thing Model

Commands¶

Über Commands steuert eine Oberfläche ein Gerät. Der Endpunkt nimmt einen Befehl für eine Capability entgegen, das Backend leitet ihn anschließend per MQTT an das Gerät weiter (siehe MQTT – Command-Daten).

Methode & Pfad	Beschreibung
`POST /devices/:uuid/command`	Befehl an ein Gerät senden

Ein Befehl besteht aus der zu steuernden Capability und dem einzustellenden Wert:

{ "capability": "brightness", "value": 80 }

Fehlt capability oder value, gibt das Backend einen 400 Bad Request-Fehler zurück. Optional kann ein Client direkt eine eigene command_id mitschicken, um sicherzustellen, dass derselbe Befehl nicht mehrfach verarbeitet wird. Andernfalls vergibt das Backend eine.

Telemetrie¶

Die Telemetrie-Endpunkte geben die von den Geräten gemeldeten Messwerte zurück. Für die Darstellung in einem Diagramm mit mehreren Datenpunkten als nur dem letzten Wert lässt sich der Zeitraum eingrenzen. Für einfache Statusanzeigen sowie beim Abrufen der Telemetrie beim Aufbau der Oberfläche genügt der jeweils letzte Wert.

Methode & Pfad	Beschreibung
`GET /devices/:uuid/telemetry`	Telemetrie-Verlauf eines Geräts
`GET /devices/:uuid/telemetry/latest`	Nur der zuletzt gemeldete Datenpunkt

Der Verlauf lässt sich über Query-Parameter eingrenzen: timespan (Zeitfenster, Standard 24 hours), alternativ start_date und end_date für einen festen Bereich sowie limit für die maximale Anzahl Datenpunkte mit einem Limit von 100 Datenpunkten.

Regeln¶

Die Automationen bzw. Regeln werden ebenfalls über die REST-API verwaltet. Um die Regeln abzurufen, zu erstellen, zu ändern, löschen, deaktivieren oder zu testen bietet die API folgende Endpunkte:

Methode & Pfad	Beschreibung
`GET /rules`	Alle Regeln auflisten
`POST /rules`	Neue Regel anlegen
`GET /rules/:id`	Einzelne Regel abrufen
`PUT /rules/:id`	Regel vollständig aktualisieren
`PATCH /rules/:id/toggle`	Regel aktivieren oder deaktivieren
`DELETE /rules/:id`	Regel löschen
`POST /rules/:id/trigger`	Regel manuell auslösen

Swagger API-Dokumentation¶

Als weiterführende Dokumentation der REST-API steht über die OpenAPI Docstrings eine interaktive Dokumentation zur Verfügung:

hub.finishing2026.sw2e-lab.de/api/v1/docs