API

ZiggyMeter stellt eine einfache, sichere REST-API für Konfiguration, Status und Integrationen zur Verfügung. Diese Seite fasst zusammen, wie Sie eine Verbindung herstellen und sich authentifizieren, bevor Sie die Endpunkte nutzen.

Eine vollständige Liste der Endpunkte finden Sie im Kapitel Endpunkte.

Transport

• Nur HTTPS: Alle Anfragen erfolgen über TLS auf Port 443.
• Standardmäßig JSON: Senden Sie Content-Type: application/json und erwarten Sie JSON-Antworten, sofern nicht anders angegeben.

Authentifizierung

Header-Format:

Authorization: Bearer <token>

Gültigkeitsdauer des Tokens:

• Tokens sind zeitlich begrenzt. Die Login-Antwort gibt die verbleibende Gültigkeit in Sekunden über expires_in_secs zurück.
• Erneuern Sie den Token, bevor er abläuft, oder behandeln Sie 401 Unauthorized, indem Sie sich erneut anmelden.

Beispiel für eine Login-Antwort:

{
    "token": "<token>",
    "expires_in_secs": 3600
}

Schnellstart

1. Token anfordern

   curl -X POST \
   https://<host>/login \
   -H "Content-Type: application/json" \
   -d '{
       "username": "<username>",
       "password": "<password>"
   }'

2. Beliebige API mit dem Token aufrufen

   curl -X GET \
   https://<host>/api/v1/system/status \
   -H "Authorization: Bearer <token>" \
   -H "Accept: application/json"

   Wenn der Token fehlt oder ungültig ist, gibt die API einen Authentifizierungsfehler zurück.

3. Abmelden

   curl -X POST \
   https://<host>/api/v1/system/logout \
   -H "Authorization: Bearer <token>"

Das Aufrufen von Logout macht den aktuellen Token sofort ungültig; weitere Anfragen mit diesem Token schlagen mit Authentifizierungsfehlern fehl. Um fortzufahren, fordern Sie durch erneutes Anmelden einen neuen Token an.

Hinweis

Zu Testzwecken können Sie die Option -k bei curl in Erwägung ziehen, die Verbindungen zu selbstsignierten oder anderweitig nicht vertrauenswürdigen Zertifikaten zulässt.

Sicherere Alternativen: Installieren Sie ein gültiges Zertifikat auf dem Server oder verweisen Sie curl mit --cacert <ca.pem> auf eine vertrauenswürdige CA (oder verwenden Sie den Trust-Store Ihres Systems).

Upgrade

Begrenzen Sie beim Durchführen eines Upgrades die Daten-Upload-Rate, da das Gerät sonst einen Fehler meldet. Das folgende Beispiel zeigt die Drosselung mit der Option --limit-rate von curl.

curl -X POST  \
https://<host>/api/v1/system/ota \
-H "Authorization: Bearer <token>" \
--data-binary "@XXXX-YYYY-00320-20250324T195250-ZiggyMeter-1.2.320.ota" \
--limit-rate 1024