REST API en webhooks

De API geeft gegevens op het moment dat je software erom vraagt. Een webhook stuurt een bericht naar je server zodra er iets gebeurt. Voor de API heb je een systeem nodig dat HTTPS-verzoeken verstuurt, voor een webhook een systeem dat ze ontvangt.

Wat je nodig hebt

• De rol Eigenaar of Beheerder om een API-sleutel of webhook aan te maken. Andere rollen zien API-sleutels en Webhooks niet onder Instellingen.
• Een API-sleutel. Hoe je die maakt, staat in API-sleutel aanmaken.

Wat je met de API ophaalt

De tabel laat zien welke gegevens je ophaalt en welk recht de sleutel daarvoor nodig heeft.

Elk verzoek gaat naar https://api.modbuscloud.com/v1, met de sleutel als bearer-token in de header Authorization. In de paden heet een gateway device.

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

Gebeurtenissen ontvangen met een webhook

Een webhook stuurt een POST-verzoek met JSON naar je eigen adres zodra er iets gebeurt. Per webhook kies je welke gebeurtenissen hij doorstuurt:

• Een alarm gaat af, keert terug, wordt bevestigd of wordt opgelost (alert.triggered, alert.returned, alert.acknowledged, alert.resolved).
• Een gateway gaat offline of komt weer online (device.offline, device.online).
• Een automatisering voert een webhook-actie uit (automation.triggered).

Elk bericht is ondertekend volgens Standard Webhooks, met een geheim dat begint met whsec_. Komt een bericht niet aan, dan probeert het portaal het opnieuw, tot zes pogingen in ruim zeven uur. Hoe je een webhook toevoegt en test, staat in Webhook instellen.

De API-referentie

De API-referentie beschrijft in het Engels de endpoints, de velden, de foutcodes en de webhookberichten. Elk endpoint probeer je daar direct uit in de browser.

Wil je een client genereren, gebruik dan het OpenAPI 3.1-bestand op https://docs.modbuscloud.com/openapi.json.

Met de sandboxsleutel uitproberen

Zonder eigen sleutel probeer je de API uit met de openbare sandboxsleutel uit de quickstart van de API-referentie. Die sleutel leest alleen en hoort bij het demo-account, het portaal van een fictief installatiebedrijf. In de referentie staat hij al ingevuld. Iedereen deelt dezelfde sleutel, dus mag elke bezoeker 60 verzoeken per minuut doen.

Grenzen en foutmeldingen

Een sleutel mag 100 verzoeken per minuut doen. De teller begint aan het begin van elke minuut opnieuw. Ga je over de grens, dan antwoordt de API met status 429 en noemt Retry-After het aantal seconden tot je verder kunt.

Vraag je elke minuut de registers van 50 gateways op, dan gebruik je al de helft van die grens. Laat alarmen daarom binnenkomen via een webhook in plaats van ze steeds op te vragen.

Een fout komt als Problem Details volgens RFC 9457. Laat je software reageren op het veld code, want de tekst in detail kan veranderen. Alle codes staan in de lijst met foutcodes. Elk antwoord heeft een header X-Request-Id. Noem die als je hulp vraagt.

Hoe de API waarden teruggeeft

Een waarde komt omgerekend met de schaalfactor van het register, net als in het portaal. De ruwe waarde uit het register komt mee. Leest een register 2314 met schaalfactor 0,1, dan geeft de API "latest_value": 231.4 en "latest_raw_value": 2314.

Toont het portaal bij een register een statustekst of de tekst van een foutcode, dan geeft de API alleen het getal. Tijden staan in UTC, in het formaat ISO 8601.

Historie in pagina's ophalen

De historie komt in pagina's van hooguit 1000 metingen. Elke pagina geeft meta.next_cursor terug. Stuur die als cursor mee in het volgende verzoek, tot meta.has_more op false staat. Zo mis je geen meting en krijg je er geen dubbel, ook niet als er tussendoor nieuwe binnenkomen.

Eén verzoek beslaat hooguit 7 dagen, of 366 dagen als je één register opgeeft. Zonder tijdvak krijg je de laatste 24 uur.

De historie bewaart per register hooguit één meting per minuut. Standaard leest de gateway elke 300 seconden (5 minuten) uit. Hoe je dat aanpast, staat in Uitleesinterval kiezen. Heb je eenmalig een bestand voor Excel nodig, gebruik dan Metingen downloaden.

Sleutels en webhooks horen bij de organisatie

Een API-sleutel en een webhook gelden voor de hele organisatie, niet voor één klant of locatie. Een sleutel leest dus de gateways van al je klanten.

De API en webhooks horen bij de portaallicentie, zonder kosten per verzoek. Waar de API draait en waar je data staat, lees je in Waar je data staat en wie erbij kan.