Monitoraggio API: quando un HTTP 200 non basta

Un'API JSON può restituire un HTTP 200 con un corpo che segnala un errore - un monitoraggio basato sul codice di stato lo dichiara UP. Il vero monitoraggio API controlla anche il contenuto della risposta, non solo l'HTTP.

Il problema: HTTP 200 ≠ API funzionante

Secondo le convenzioni delle API REST, i codici di stato dovrebbero essere usati correttamente (200 OK, 4xx errore client, 5xx errore server). Nella pratica:

Alcune API restituiscono sempre 200, l'errore è nel corpo JSON
Un API gateway può trasformare un 5xx in un 200 con un JSON di errore
Gli endpoint BFF del frontend spesso incapsulano i backend e restituiscono 200 se la comunicazione è avvenuta, anche se il backend è fallito
Gli endpoint GraphQL restituiscono tipicamente 200; gli errori (errors) si trovano nel campo errors[]

Dalla prospettiva del monitoraggio classico (codice di stato HTTP) è tutto a posto. Dalla prospettiva del client reale, l'API si è rotta.

Content matching: parole chiave

Il complemento più semplice del monitoraggio HTTP è la corrispondenza di una parola chiave. Definisci una stringa che deve essere presente nella risposta - se manca, arriva una notifica.

Esempio per un endpoint di health check:

GET /api/health HTTP/1.1

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

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

Negative matching: ciò che dovrebbe mancare

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

"error" - errore nel corpo
"maintenance" - modalità manutenzione inattesa
"deprecated" - l'endpoint API è stato contrassegnato come obsoleto (deprecated)
frammenti di errore SQL: "SyntaxError", "undefined", "null pointer" - errori di backend che trapelano

Asserzioni avanzate

La corrispondenza di testo semplice ha i suoi limiti. Per un monitoraggio API serio sono adatte asserzioni strutturate sulla struttura JSON (espressioni JSONPath) e transazioni sintetiche a più passaggi (login -> endpoint protetto -> logout).

ePulz.io supporta queste possibilità in modo diretto. Il monitoraggio multi-step / API permette di concatenare fino a 10 passaggi (GET/POST/PUT/PATCH/DELETE/HEAD), verificando a ogni passaggio il codice di stato, il contenuto e anche il valore JSONPath, oltre a salvare variabili dalla risposta per i passaggi successivi. La funzione è disponibile sui piani Profi e Business e gira sulla regione primaria. Per i casi più semplici sui piani inferiori puoi combinare un monitor HTTP con uno script ausiliario separato che invia il risultato tramite un monitor heartbeat.

Autenticazione nel monitoraggio

L'endpoint monitorato richiede spesso l'autenticazione. Le opzioni:

Bearer token nell'header Authorization - tipicamente un token di monitoraggio long-lived senza scadenza (va conservato in modo sicuro)
API key nel parametro query - visibile nei log, sconsigliato
Firma HMAC - timestamp + URL + hash del corpo firmati con un segreto condiviso. Il metodo più sicuro.
mTLS - certificato client sul lato del monitoraggio. Adatto alle API interne.

Avviso di sicurezza: Per il monitoraggio crea un account / token dedicato con i permessi minimi (endpoint di health in sola lettura, non un token di amministrazione). Ruota il token regolarmente. Se il servizio di monitoraggio viene compromesso, non trapela l'intero accesso all'API.

SLO del tempo di risposta

Il tempo di risposta dell'API è importante quanto il codice HTTP. Un client con timeout di 30 s non vede la differenza tra "l'API restituisce 200 in 25 s" e "l'API è terminata in timeout". Dal punto di vista della UX, entrambi sono pessimi.

Imposta:

Hard timeout - dopo 10-15 s il monitoraggio segnala DOWN
Soglia soft - tempo di risposta tra 500 e 2000 ms = warning (prestazioni degradate)
Notifiche sulle tendenze - una notifica se il 95° percentile del tempo di risposta sale del 50 % nelle ultime 24 h

Monitoraggio per endpoint

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

Le business operations più usate (POST /api/orders, GET /api/dashboard)
Un endpoint di lettura che verifica il cache hit (risposta veloce)
Un endpoint di scrittura con roundtrip sul DB
Un endpoint di integrazione esterna (chiama una terza parte - rileva i guasti delle dipendenze)

Monitora ognuno separatamente. Così, in caso di incidente, vedi esattamente quale parte dell'API è caduta.

Conclusione

Il monitoraggio API non si può ridurre al codice di stato HTTP. Un monitoraggio di qualità combina stato + content match + tempo di risposta + granularità per endpoint + autenticazione, per imitare fedelmente un client reale - non solo un client HTTP.

Monitoraggio API con corrispondenza di parola chiave

Codice di stato + parola chiave nel contenuto + tempo di risposta + auth header. Granularità per endpoint.

Avvia il monitoraggio →