Monitoraggio API: come controllare la risposta JSON, non solo HTTP 200

In breve: Un'API JSON può restituire HTTP 200 con corpo {"status":"error","message":"DB unavailable"} - il monitoraggio che osserva solo lo status code annuncia "UP". Il vero monitoraggio API controlla anche il contenuto della risposta, non solo il layer HTTP.

Il problema: HTTP 200 != API funzionante

Le convenzioni REST API dicono di usare gli status code correttamente (200 OK, 4xx client error, 5xx server error). In pratica:

• Alcune API restituiscono sempre 200, l'errore è nel body JSON
• Un API gateway può trasformare 5xx in 200 con error JSON
• Gli endpoint frontend BFF spesso wrappano backend e restituiscono 200 se la comunicazione è avvenuta, anche se il backend ha fallito
• Gli endpoint GraphQL restituiscono sempre 200, gli errori sono nel campo errors[]

Dal punto di vista del monitoraggio classico (status code HTTP) tutto è OK. Dal punto di vista del client reale l'API è rotta.

Content matching: keyword

L'aggiunta più semplice al monitoraggio HTTP è keyword match. Definisci una stringa che deve essere nella risposta - se manca, alert.

Esempio per endpoint health check:

GET /api/health HTTP/1.1

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

Imposta keyword match su "status":"ok". Se il DB cade e l'endpoint restituisce "status":"degraded", il monitoraggio lo cattura.

Negative matching: cosa dovrebbe mancare

A volte è più utile controllare che una certa stringa NON sia nella risposta:

• "error" - errore nel body
• "maintenance" - modalità maintenance inattesa
• "deprecated" - endpoint API diventato deprecated
• frammenti di errore SQL: "SyntaxError", "undefined", "null pointer" - errori backend che trapelano

Asserzioni avanzate - roadmap

Il match in testo semplice ha limiti. Per un monitoraggio API serio, sono appropriate asserzioni strutturate su struttura JSON (espressioni JSONPath) e transazioni sintetiche multi-step (login -> endpoint protetto -> logout).

Le asserzioni JSONPath e le transazioni sintetiche multi-step sono nella roadmap di ePulz.io ma attualmente non sono implementate. Se ne hai bisogno oggi, combina un monitor HTTP ePulz.io con il tuo script che invia il risultato attraverso un monitor heartbeat (in caso di fallimento semplicemente non inviare l'heartbeat).

Authentication nel monitoraggio

L'endpoint monitorato spesso richiede auth. Opzioni:

• Bearer token nell'header Authorization - tipicamente token di monitoraggio long-lived senza scadenza (da conservare in modo sicuro)
• Chiave API nel parametro query - visibile nei log, non preferito
• Firma HMAC - timestamp + URL + hash del body firmato con shared secret. Più sicuro.
• mTLS - cert client lato monitoraggio. Adatto per API interne.

Avviso di sicurezza: Per il monitoraggio crea un account / token dedicato con permessi minimi (endpoint health read-only, non token admin). Ruota il token regolarmente. Se il servizio di monitoraggio ha un leak, non esce l'intero accesso all'API.

Response time SLO

Il response time API è importante quanto il codice HTTP. Un client con timeout 30 s non vede differenza tra "API restituisce 200 in 25 s" e "API in timeout". Dal punto di vista UX entrambi sono brutti.

Imposta:

• Hard timeout - dopo 10-15 s il monitoraggio annuncia DOWN
• Soft threshold - response time tra 500-2000 ms = warning (degraded performance)
• Trending alerts - alert se il 95° percentile del response time sale del 50% nelle ultime 24 h

Monitoraggio per endpoint

Una grande API ha decine di endpoint. Non monitorare solo /health - anche lui può mentire. Identifica 3-5 endpoint critici:

• Business operation più usate (POST /api/orders, GET /api/dashboard)
• Read endpoint per cache hit (risposta veloce)
• Write endpoint con roundtrip DB
• Endpoint di integrazione esterna (chiama terza parte - rileva outage delle dipendenze)

Monitora ciascuno separatamente. Durante un incident vedi esattamente quale parte dell'API è caduta.

Conclusione

Il monitoraggio API non può essere ridotto allo status code HTTP. Un monitoraggio di qualità combina status + content match + response time + granularità per endpoint + authentication, per somigliare a un client reale - non solo un client HTTP.

Monitoraggio API con keyword match

Status code + keyword nel contenuto + response time + auth header. Granularità per endpoint.

Prova per 7 giorni →