REST-API¶

Die WattWächter REST API ist unter http://wattwaechter-XXXXXXXXXXXX.local/api/v1/ erreichbar und bietet vollen Zugriff auf Gerätedaten, Einstellungen und Steuerungsfunktionen.

Authentifizierung¶

Ab Werk deaktiviert

Die API-Authentifizierung ist ab Werk deaktiviert. Alle Endpunkte sind ohne Token erreichbar. Die Authentifizierung kann über die Einstellungen aktiviert werden (api_auth_required: true).

Wenn aktiviert, verwendet die API Bearer Tokens im Authorization-Header:

Authorization: Bearer DEIN_TOKEN

Es gibt zwei Token-Stufen:

READ Token — Daten lesen (History, Status, Einstellungen anzeigen)
WRITE Token — Einstellungen ändern, OTA starten, Reboot auslösen

Token erneuern

Tokens können über einen zweistufigen Prozess erneuert werden:

POST /api/v1/auth/tokens/generate — Generiert neue Tokens (noch nicht aktiv)
POST /api/v1/auth/tokens/confirm — Aktiviert die neuen Tokens (innerhalb von 60 Sekunden)

Dieser Zwei-Phasen-Ansatz verhindert ein Aussperren, falls die Antwort verloren geht.

Rate Limits & Fehlercodes¶

Da der WattWächter auf einem ESP32 mit begrenztem Arbeitsspeicher läuft, sind eingehende API-Anfragen begrenzt. Clients sollten den Retry-After-Header beachten und Anfragen entsprechend zurückstellen.

Rate Limit¶

Es sind maximal 25 Anfragen pro 10 Sekunden erlaubt (geräteweit, nicht pro IP — mehrere Clients teilen sich das Budget). Wird das Limit überschritten, antwortet das Gerät mit:

HTTP/1.1 429 Too Many Requests
Retry-After: 10
Content-Type: application/json

{"error":"Too many requests"}

Heap-Schutz¶

Sinkt der freie Heap unter eine kritische Schwelle (25 KB), werden neue API-Anfragen kurzzeitig abgelehnt, um das Gerät stabil zu halten:

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{"error":"Service temporary unavailable"}

Tritt typischerweise bei sehr großen Antworten (z. B. langen History-Zeiträumen) unter gleichzeitiger Last auf. Ein Wiederholungsversuch nach wenigen Sekunden ist in der Regel erfolgreich.

Python-Client

Die Python-Bibliothek berücksichtigt sowohl 429 als auch 503 automatisch und respektiert den Retry-After-Header.

Endpunkt-Übersicht¶

System¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/system/alive`	—	Healthcheck
GET	`/api/v1/system/info`	READ	Systeminformationen
GET	`/api/v1/system/led`	READ	LED-Status
GET	`/api/v1/system/wifi_scan`	—	WLAN-Scan
GET	`/api/v1/system/timezones`	READ	Zeitzonen-Liste
POST	`/api/v1/system/reboot`	WRITE	Neustart

History¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/history/latest`	READ	Aktuellster Messwert
GET	`/api/v1/history/highRes?date=YYYY-MM-DD`	READ	15-Min-Daten für einen Tag
GET	`/api/v1/history/lowRes?start=YYYY-MM-DD&days=7`	READ	Tageswerte

Einstellungen¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/settings`	READ	Einstellungen lesen
POST	`/api/v1/settings`	WRITE	Einstellungen ändern (partiell)
POST	`/api/v1/auth/tokens/generate`	WRITE	Neue Tokens generieren
POST	`/api/v1/auth/tokens/confirm`	WRITE	Tokens aktivieren
GET	`/api/v1/mqtt/ca`	READ	CA-Zertifikat-Status
POST	`/api/v1/mqtt/ca`	WRITE	CA-Zertifikat hochladen
DELETE	`/api/v1/mqtt/ca`	WRITE	CA-Zertifikat löschen
POST	`/api/v1/cloud/pair`	WRITE	Cloud-Pairing-Token senden
DELETE	`/api/v1/cloud/pair`	WRITE	Cloud-Pairing aufheben

OTA¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/ota/check`	READ	Update prüfen
POST	`/api/v1/ota/start`	WRITE	Update starten

Logs¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/logs/rawdump`	READ	SmartMeter Ringbuffer (binär)
GET	`/api/v1/logs/persistent`	READ	Persistentes CSV-Logfile
GET	`/api/v1/logs/ram`	READ	RAM-Log Snapshot (CSV)

Modbus TCP¶

Methode	Endpunkt	Auth	Beschreibung
GET	`/api/v1/modbus/status`	READ	Modbus-Server-Status und aktuelle Register-Belegung

→ Details & Aktivierung: Modbus TCP

Interaktive API-Dokumentation¶

Die vollständige API-Spezifikation im OpenAPI-Format:

Hinweis

Die API-Dokumentation wird automatisch aus der Firmware-OpenAPI-Spezifikation generiert.