API-monitoring

Waarom heeft een API eigen monitoring nodig

Een API is niet simpelweg een pagina onder /api/. Het is een contract. De HTTP-methode doet ertoe – GET vs POST verandert de betekenis. Headers dragen authenticatie, content negotiation, idempotency-keys. De request body is de input. De response code is belangrijk (401 vs 403 vs 422 – elk vertelt een ander verhaal). De response body heeft een structuur – de JSON-paden waarop integrators vertrouwen. Een gewone uptime-check die enkel een GET op de URL doet, mist de meeste manieren waarop een API kan falen: ongeldige JSON die nog steeds 200 teruggeeft, een authenticatie-endpoint dat verkeerde gegevens accepteert, een webhook met een kapotte payload-structuur, een endpoint dat 200 retourneert maar binnenin "status": "error" geeft.

API-monitoring lost dit op door je volledige controle te geven over elk deel van de request en elk onderdeel van de response-verificatie. Je configureert exact dezelfde call die jouw integrators doen – dezelfde methode, dezelfde headers, dezelfde body, dezelfde authenticatie – en precies wat succes betekent – de exacte codes, waarden onder JSON-paden, responsetijd-drempels, groottegrenzen.

Requestconfiguratie

Voor elke API-monitor in DiagnoSEO Uptime Monitoring kun je het volgende instellen:

• HTTP-methode: GET, POST, PUT, PATCH, DELETE, HEAD. Kies de methode die je integrators gebruiken.
• Eigen headers: als een JSON-object, bv. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standaard voor het testen van OAuth, JWT, API-sleutels, content negotiation.
• Request body: elke string – JSON, XML, form-encoded, plain text. Wordt meegegeven bij POST/PUT/PATCH/DELETE.
• Basic auth: gebruikersnaam en wachtwoord, als de endpoint zo beveiligd is.
• Verwachte statuscodes: lijst of bereik. Standaard 200-399, maar je kunt beperken tot één specifieke code (bijv. exact 201 voor een creatie-endpoint) of specifieke toestaan (bijv. 200,202,204).

De check volgt maximaal 5 redirects, decodeert gzip, leest de Content-Type om JSON te detecteren. Elke controle logt de werkelijke code, responsetijd, grootte en eventuele fout. Meerdere opeenvolgende storingen (instelbaar, standaard 2) leiden tot een incident.

JSON path-asserties

Alleen statuscodes zijn vaak niet genoeg voor veel API's. Een health-endpoint kan 200 retourneren met body {"status": "degraded", "db": "down"} – nog steeds 200, maar dat wil je echt weten. Een prijs-API kan 200 geven met body waarbij data.price op null staat. Een zoek-API kan 200 geven met results: [], omdat de index eruit ligt.

Voor zulke gevallen stel je een JSON path-assertie in. Geef het pad op (bijv. data.status of health.checks.db) en de verwachte waarde (bijv. healthy, true of een specifiek getal). Bij elke controle wordt de response uitgelezen als JSON en wordt de waarde onder het pad vergeleken. Als het niet overeenkomt, faalt de check direct, ongeacht de HTTP-status.

De padnotatie gebruikt puntnotatie met haakjes: data.items[0].id werkt, net als users.john.email. De ge-assertede waarde wordt als string vergeleken, dus "true" matcht met bool true, en getallen matchen als string én als getal.

Authenticatiepatronen

De twee meest voorkomende authenticatiestijlen werken uit de doos. Voor Bearer tokens (OAuth, JWT, API keys) gebruik je het veld headers: {"Authorization": "Bearer eyJhbGciOi..."}. De token staat in de monitorconfiguratie en wordt bij elke check toegevoegd. Voor basic auth gebruik je de aparte velden gebruikersnaam/wachtwoord – deze worden bewaard en samengevoegd tot de standaardheader.

Als authenticatie per request gesigneerd of token-refreshing vereist, wordt het ingewikkelder. Twee redelijke patronen: (1) maak een langlevende servicetoken speciaal voor monitoring, of (2) maak een ongeauthenticeerd health-endpoint dat de status van het echte beveiligde endpoint reflecteert, en monitor dát. De meeste moderne API’s bieden dit standaard aan.

Aanbevolen patronen

• Eén monitor per kritisch endpoint. Test niet alles – kies 5-10 endpoints waar uitval meteen grote impact heeft.
• Gebruik exacte codes. Standaard 200-399 is te ruim voor API’s. Een creatie-endpoint moet exact 201 teruggeven; een idempotent endpoint exact 200; een login-endpoint exact 200 (succes) of 401 (goed geformatteerde mislukking – geen 500).
• Koppel status aan JSON-assertie. Samen vangen ze regressies op transport- én contentniveau. Alleen status pakt contentfouten niet op; alleen een JSON-assertie is kwetsbaar bij redirects.
• Stel een responsetijd-drempel in. Degradatie van de API is een vroeg indicatiesignaal voor afhankelijkheidsproblemen. Een monitor met rt_threshold_ms = 800 meldt dat de API traag wordt voordat hij uitvalt.
• Houd de body klein. Check draait elke minuut – grote bodies verspillen bandbreedte aan beide kanten. Representatieve maar minimale payloads zijn genoeg.

Combineren met andere monitortypes

Voor elke API-endpoint controleert de API-monitor dat de call werkt. Een aparte ping- of poortmonitor controleert of de host bereikbaar is. Een SSL-/domeincheck op dezelfde hostnaam pakt certificaat- en registratieproblemen direct op. Een extra DNS-submonitor bewaakt wijzigingen in records die op omleiding kunnen wijzen. Samen geven vier monitors op een API een volledig beeld met minimaal overlap.

Configuratie

Open de tool, klik op "Monitor toevoegen", kies type "API". Plak de URL. Open de sectie Geavanceerd. Selecteer de methode, plak de headers als JSON, plak de body indien nodig, stel basic auth in als je dat gebruikt, geef de verwachte codes in (bijv. 200 of 200,201). Voeg een JSON path-assertie toe indien van toepassing. Stel interval en bevestigingsdrempel in. Sla op. Vanaf de volgende cyclus roept de monitor je API precies aan zoals een integrator zou doen, valideert het antwoord en waarschuwt bij regressie onmiddellijk.

Veelgestelde vragen

• Welke HTTP-methodes kan ik gebruiken voor API-monitoring?

  GET, POST, PUT, DELETE, PATCH en HEAD. Configureer de methode per monitor — voor write-endpoints (POST/PUT/PATCH) kan de request body ook ingesteld worden als JSON-string of form data.

• Hoe werken JSON-asserties?

  Je geeft een JSON-pad op (bijv. data.status of results[0].id) en de verwachte waarde. De monitor haalt het antwoord op, parseert als JSON, extraheert het pad en vergelijkt met de verwachte waarde. Komt het niet overeen, dan faalt de check met de foutmelding "assertion failed" en de echte waarde.

• Kan ik authenticatie-headers meesturen?

  Ja. Aangepaste HTTP-headers zijn per monitor instelbaar – Authorization-tokens, API-sleutels, content-type, alles wat nodig is. Headerwaarden worden versleuteld opgeslagen in de database. Voor Basic Auth is er een apart veld voor gebruikersnaam/wachtwoord dat automatisch de request ondertekent.

• Wat als mijn API 200 teruggeeft met een fout-payload?

  Veelvoorkomend patroon: API geeft HTTP 200 terug maar de body zegt {"status":"error"}. Een naïeve uptime-monitor denkt dat dit gezond is. Gebruik een JSON-assertie status == "ok" om dit op te pakken — de assertie faalt en de monitor meldt DOWN, ook al geeft HTTP 200.

• Hoe ga ik om met een API met rate limit?

  Stel het check-interval zo in dat het de API-limiet respecteert (bijv. een interval van 5 minuten als je API 12 calls/uur toestaat). Een check telt als één API-call per check per regio. Multi-region checks vermenigvuldigen het aantal calls – gebruik single-region monitoring als jouw API strikte limieten kent.