API monitoring: hoe JSON-respons controleren, niet alleen HTTP 200

Kort: Een JSON API kan HTTP 200 retourneren met body {"status":"error","message":"DB unavailable"} - monitoring die alleen de statuscode bekijkt, meldt "UP". Echte API-monitoring controleert ook de inhoud van het antwoord, niet alleen de HTTP-laag.

Het probleem: HTTP 200 != werkende API

REST API-conventies zeggen statuscodes correct te gebruiken (200 OK, 4xx client error, 5xx server error). In de praktijk:

• Sommige API's retourneren altijd 200, de fout zit in de JSON body
• Een API gateway kan 5xx omzetten naar 200 met error JSON
• Frontend BFF endpoints wrappen vaak backends en retourneren 200 als de communicatie plaatsvond, ook al faalde de backend
• GraphQL endpoints retourneren altijd 200, errors zitten in het errors[] veld

Vanuit het perspectief van klassieke monitoring (HTTP statuscode) is alles OK. Vanuit het perspectief van de echte client is de API stuk.

Content matching: keywords

De simpelste aanvulling op HTTP monitoring is keyword match. Je definieert een string die moet voorkomen in het antwoord - als hij ontbreekt, alert.

Voorbeeld voor een health check endpoint:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Stel keyword match in op "status":"ok". Als de DB uitvalt en de endpoint "status":"degraded" retourneert, vangt monitoring het op.

Negative matching: wat zou moeten ontbreken

Soms is het nuttiger om te controleren dat een bepaalde string NIET in het antwoord staat:

• "error" - fout in de body
• "maintenance" - onverwachte maintenance modus
• "deprecated" - API endpoint werd deprecated
• SQL error fragmenten: "SyntaxError", "undefined", "null pointer" - lekkende backend fouten

Geavanceerde asserties - roadmap

Plain text match heeft beperkingen. Voor serieuze API-monitoring zijn gestructureerde asserties over JSON-structuur (JSONPath-expressies) en multi-step synthetic transacties (login -> beschermd endpoint -> logout) geschikt.

JSONPath-asserties en multi-step synthetic transacties staan op de ePulz.io-roadmap maar zijn momenteel niet geïmplementeerd. Heeft u ze vandaag nodig, combineer dan een ePulz.io HTTP-monitor met uw eigen script dat het resultaat via een heartbeat-monitor stuurt (bij fout simpelweg de heartbeat niet sturen).

Authentication in monitoring

De gemonitorde endpoint vereist vaak auth. Opties:

• Bearer token in Authorization header - typisch long-lived monitoring token zonder verloop (moet veilig opgeslagen worden)
• API key in query parameter - zichtbaar in logs, niet de voorkeur
• HMAC handtekening - timestamp + URL + body hash ondertekend met shared secret. Veiligste.
• mTLS - client cert aan monitoring kant. Geschikt voor interne API's.

Beveiligingswaarschuwing: Voor monitoring maak een dedicated account / token aan met minimale rechten (read-only health endpoint, geen admin token). Roteer het token regelmatig. Als de monitoring service lekt, lekt niet de hele API-toegang.

Response time SLO

API response time is net zo belangrijk als de HTTP code. Een client met timeout 30 s ziet geen verschil tussen "API retourneert 200 in 25 s" en "API timeout". Vanuit UX zijn beide slecht.

Stel in:

• Hard timeout - na 10-15 s meldt monitoring DOWN
• Soft threshold - response time tussen 500-2000 ms = warning (degraded performance)
• Trending alerts - alert als 95e percentiel response time 50% stijgt in de laatste 24 u

Per-endpoint monitoring

Een grote API heeft tientallen endpoints. Monitor niet alleen /health - zelfs die kan liegen. Identificeer 3-5 kritieke endpoints:

• Meest gebruikte business operations (POST /api/orders, GET /api/dashboard)
• Read endpoint voor cache hit (snel antwoord)
• Write endpoint met DB roundtrip
• Externe integratie endpoint (roept derde partij aan - detecteert dependency uitval)

Monitor elk apart. Bij een incident zie je precies welk deel van de API uitviel.

Conclusie

API monitoring kan niet worden gereduceerd tot HTTP statuscode. Kwaliteitsmonitoring combineert status + content match + response time + per-endpoint granulariteit + authentication, om een echte client te imiteren - niet alleen een HTTP client.

API monitoring met keyword match

Statuscode + keyword in content + response time + auth headers. Per-endpoint granulariteit.

Proberen voor 7 dagen →