REST-API und Webhooks

Die API liefert Daten in dem Moment, in dem Ihre Software danach fragt. Ein Webhook sendet eine Nachricht an Ihren Server, sobald etwas passiert. Für die API brauchen Sie ein System, das HTTPS-Anfragen sendet, für einen Webhook ein System, das sie empfängt.

Was Sie brauchen

• Die Rolle Eigentümer oder Administrator, um einen API-Schlüssel oder Webhook zu erstellen. Andere Rollen sehen API-Schlüssel und Webhooks unter Einstellungen nicht.
• Einen API-Schlüssel. Wie Sie ihn erstellen, steht in API-Schlüssel erstellen.

Was Sie mit der API abrufen

Die Tabelle zeigt, welche Daten Sie abrufen und welche Berechtigung der Schlüssel dafür braucht.

Jede Anfrage geht an https://api.modbuscloud.com/v1, mit dem Schlüssel als Bearer-Token im Header Authorization. In den Pfaden heißt ein Gateway device.

curl https://api.modbuscloud.com/v1/devices \
  -H "Authorization: Bearer mlk_..."

Ereignisse per Webhook empfangen

Ein Webhook sendet eine POST-Anfrage mit JSON an Ihre eigene Adresse, sobald etwas passiert. Pro Webhook wählen Sie, welche Ereignisse er weiterleitet:

• Ein Alarm löst aus, kehrt zurück, wird bestätigt oder wird gelöst (alert.triggered, alert.returned, alert.acknowledged, alert.resolved).
• Ein Gateway geht offline oder kommt wieder online (device.offline, device.online).
• Eine Automatisierung führt eine Webhook-Aktion aus (automation.triggered).

Jede Nachricht ist nach Standard Webhooks signiert, mit einem Geheimnis, das mit whsec_ beginnt. Kommt eine Nachricht nicht an, versucht das Portal es erneut, bis zu sechs Versuche in gut sieben Stunden. Wie Sie einen Webhook hinzufügen und testen, steht in Webhook einrichten.

Die API-Referenz

Die API-Referenz beschreibt auf Englisch die Endpunkte, die Felder, die Fehlercodes und die Webhook-Nachrichten. Jeden Endpunkt probieren Sie dort direkt im Browser aus.

Möchten Sie einen Client generieren, verwenden Sie die OpenAPI-3.1-Datei unter https://docs.modbuscloud.com/openapi.json.

Mit dem Sandbox-Schlüssel ausprobieren

Ohne eigenen Schlüssel probieren Sie die API mit dem öffentlichen Sandbox-Schlüssel aus der Quickstart der API-Referenz aus. Dieser Schlüssel liest nur und gehört zum Demo-Konto, dem Portal eines fiktiven Installationsbetriebs. In der Referenz ist er bereits eingetragen. Alle teilen denselben Schlüssel, deshalb darf jeder Besucher 60 Anfragen pro Minute senden.

Grenzen und Fehlermeldungen

Ein Schlüssel darf 100 Anfragen pro Minute senden. Der Zähler beginnt mit jeder neuen Minute von vorn. Überschreiten Sie die Grenze, antwortet die API mit dem Status 429, und Retry-After nennt die Sekunden, bis Sie weitermachen können.

Fragen Sie jede Minute die Register von 50 Gateways ab, verbrauchen Sie schon die Hälfte dieser Grenze. Lassen Sie Alarme deshalb über einen Webhook eintreffen, statt sie ständig abzufragen.

Ein Fehler kommt als Problem Details nach RFC 9457. Lassen Sie Ihre Software auf das Feld code reagieren, denn der Text in detail kann sich ändern. Alle Codes stehen in der Liste der Fehlercodes. Jede Antwort hat einen Header X-Request-Id. Nennen Sie ihn, wenn Sie Hilfe anfragen.

Wie die API Werte zurückgibt

Ein Wert kommt mit dem Skalierungsfaktor des Registers umgerechnet an, genau wie im Portal. Der Rohwert aus dem Register kommt mit. Liest ein Register 2314 mit Skalierungsfaktor 0,1, gibt die API "latest_value": 231.4 und "latest_raw_value": 2314 zurück.

Zeigt das Portal bei einem Register einen Statustext oder den Text eines Fehlercodes, gibt die API nur die Zahl zurück. Zeiten stehen in UTC, im Format ISO 8601.

Verlauf seitenweise abrufen

Der Verlauf kommt in Seiten mit höchstens 1000 Messwerten. Jede Seite gibt meta.next_cursor zurück. Senden Sie ihn als cursor in der nächsten Anfrage mit, bis meta.has_more auf false steht. So verpassen Sie keinen Messwert und erhalten keinen doppelt, auch nicht, wenn zwischendurch neue eintreffen.

Eine Anfrage umfasst höchstens 7 Tage, oder 366 Tage, wenn Sie ein einzelnes Register angeben. Ohne Zeitraum erhalten Sie die letzten 24 Stunden.

Der Verlauf speichert pro Register höchstens einen Messwert pro Minute. Standardmäßig liest das Gateway alle 300 Sekunden (5 Minuten) aus. Wie Sie das ändern, steht in Abfrageintervall wählen. Brauchen Sie einmalig eine Datei für Excel, verwenden Sie Messwerte herunterladen.

Schlüssel und Webhooks gehören zur Organisation

Ein API-Schlüssel und ein Webhook gelten für die ganze Organisation, nicht für einen einzelnen Kunden oder Standort. Ein Schlüssel liest also die Gateways aller Ihrer Kunden.

Die API und Webhooks gehören zur Portallizenz, ohne Kosten pro Anfrage. Wo die API läuft und wo Ihre Daten liegen, lesen Sie in Wo Ihre Daten liegen und wer darauf zugreifen kann.