Monitoraggio API

Perché le API necessitano di un monitoraggio dedicato

Un'API non è semplicemente una pagina su /api/. È un contratto. Il metodo HTTP è importante - GET vs POST cambia la semantica. Gli header trasportano autenticazione, content negotiation, chiavi di idempotenza. Il body della richiesta è l’input. Il codice di risposta ha un significato (401 vs 403 vs 422 - ognuno racconta una storia diversa). Il body della risposta ha una struttura - i percorsi JSON su cui fanno affidamento gli integratori. Un semplice controllo dell’uptime, che lancia solo una GET sull’URL, si perde la maggior parte dei modi in cui una API può fallire: JSON errato che restituisce comunque 200, endpoint di autenticazione che accetta dati sbagliati, webhook con schema payload errato, endpoint che restituisce 200 ma con "status": "error" all’interno.

Il monitoraggio delle API risolve tutto questo, dandoti controllo su ogni parte della richiesta e su ogni parte della verifica della risposta. Configuri esattamente la chiamata che fanno i tuoi integratori – stesso metodo, stessi header, stesso body, stessa autenticazione – e esattamente ciò che significa "successo": codici precisi, valori su percorsi JSON, soglie di tempo di risposta, limiti di dimensione.

Configurazione della richiesta

Per ogni monitor API in DiagnoSEO Uptime Monitoring puoi configurare:

• Metodo HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Scegli quello usato dagli integratori.
• Header personalizzati: come oggetto JSON, es. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standard per testare OAuth, JWT, chiavi API, content negotiation.
• Body della richiesta: qualsiasi stringa - JSON, XML, form-encoded, testo semplice. Inviato per POST/PUT/PATCH/DELETE.
• Basic auth: utente e password, se l'endpoint è protetto in questo modo.
• Codici di stato attesi: lista o intervallo. Di default 200-399, ma puoi restringere a un singolo codice (es. esattamente 201 per un endpoint di creazione) oppure permettere specifici (es. 200,202,204).

Il controllo segue fino a 5 redirect, decodifica gzip, analizza il Content-Type per rilevare JSON. Ogni controllo salva il vero codice, tempo di risposta, dimensione e qualsiasi errore. Vari fallimenti consecutivi (configurabili, di default 2) attivano un incidente.

Asserzioni JSON path

I soli codici di stato non bastano per molte API. Un endpoint di health può restituire 200 con body {"status": "degraded", "db": "down"} – sempre 200, ma è fondamentale saperlo. Una API prezzi può restituire 200 con un body in cui data.price è diventato null. Un API di ricerca può restituire 200 con results: [] perché l’indice è giù.

Per questi casi configura un’asserzione JSON path. Imposta il percorso (es. data.status o health.checks.db) e il valore atteso (es. healthy, true o un numero specifico). Ad ogni controllo la risposta viene decodificata da JSON, e il valore sul percorso confrontato. Un mismatch fa fallire il check, indipendentemente dallo status HTTP.

La sintassi del percorso è la notazione puntata con parentesi: data.items[0].id funziona, così come users.john.email. Il valore asserito è confrontato come stringa, quindi "true" corrisponde a bool true, e i numeri corrispondono sia come stringhe che come numeri.

Pattern di autenticazione

I due stili di autenticazione più comuni funzionano immediatamente. Per i token Bearer (OAuth, JWT, chiavi API) usa il campo headers: {"Authorization": "Bearer eyJhbGciOi..."}. Il token risiede nella configurazione del monitor ed è inviato a ogni controllo. Per la basic auth usa i campi dedicati utente/password - vengono salvati e combinati nello standard header.

Se l’autenticazione richiede firma per richiesta o aggiornamento del token, è più complesso. Due pattern ragionevoli: (1) configura un token long-lived di servizio appositamente per il monitoraggio, oppure (2) esponi un endpoint di health non autenticato che rifletta lo stato di quello protetto reale, e monitora quello. La maggior parte delle API moderne lo offre già di default.

Pattern che consigliamo

• Un monitor per ogni endpoint critico. Non testarli tutti – scegline 5-10, la cui indisponibilità avrebbe un impatto reale.
• Usa codici precisi. Il default 200–399 è troppo permissivo per le API. Un endpoint di creazione dovrebbe restituire esattamente 201; uno idempotente esattamente 200; endpoint di login esattamente 200 (successo) o 401 (fallimento corretto – non 500).
• Combina stato con asserzione JSON. Insieme catturano regressioni sia sul livello di trasporto che di contenuto. Solo lo status non intercetta errori di contenuto; la sola asserzione JSON è fragile sui redirect.
• Imposta una soglia di tempo di risposta. La degradazione dell’API è un indicatore precoce di problemi con le dipendenze. Un monitor con rt_threshold_ms = 800 segnala che l’API sta rallentando, prima che cada.
• Tieni il body piccolo. I controlli vengono fatti ogni minuto – body grossi sprecano banda su entrambi i lati. Payload rappresentativi ma minimali bastano.

Combina con altri tipi di monitor

Per ogni endpoint API, il monitor API verifica che la chiamata funzioni. Un monitor ping o port separato verifica che l’host sia raggiungibile. Il controllo SSL/dominio sullo stesso hostname rileva problemi di certificato e di registrazione. Un sub-monitor DNS tiene d’occhio i cambi di record che potrebbero indicare spoofing. Insieme, quattro monitor sull’API danno una panoramica completa sovrapponendosi il minimo indispensabile.

Configurazione

Apri lo strumento, clicca su “Aggiungi monitor”, scegli il tipo "API". Incolla l’URL. Apri la sezione Avanzate. Scegli il metodo, incolla gli header come JSON, incolla il body se necessario, imposta basic auth se usata, inserisci i codici attesi (es. 200 o 200,201). Aggiungi una asserzione JSON path se serve. Imposta intervallo e soglia di conferma. Salva. Dal ciclo successivo, il monitor interrogherà la tua API esattamente come farebbe un integratore, validerà la risposta e avviserà al primo accenno di regressione.

Domande frequenti

• Quali metodi HTTP posso utilizzare per il monitoraggio API?

  GET, POST, PUT, DELETE, PATCH e HEAD. Configura il metodo per monitor — per endpoint di scrittura (POST/PUT/PATCH) anche il body della richiesta è configurabile come stringa JSON o form data.

• Come funzionano le asserzioni JSON?

  Inserisci il percorso JSON (es. data.status o results[0].id) e il valore atteso. Il monitor riceve la risposta, la analizza come JSON, estrae il percorso e lo confronta con il valore atteso. Se non corrisponde, il check fallisce segnalando "assertion failed" e mostrando il valore reale.

• Posso inviare header di autenticazione?

  Sì. Gli header HTTP personalizzati sono configurabili per monitor — token Authorization, chiavi API, content-type, qualunque cosa. I valori degli header sono criptati a riposo nel database. Per la Basic Auth è presente un campo dedicato username/password che firma automaticamente la richiesta.

• Cosa succede se la mia API restituisce 200 con payload di errore?

  Pattern comune: l’API restituisce HTTP 200 ma il body dice {"status":"error"}. Un monitor uptime ingenuo pensa che sia tutto ok. Usa un’asserzione JSON status == "ok" per intercettare questo caso – l’asserzione fallisce e il monitor segnala DOWN anche se HTTP ritorna 200.

• Come gestire una API con rate limit?

  Imposta l’intervallo di controllo per rispettare il limite API (es. intervallo di 5 minuti se la API permette 12 richieste/ora). Ogni check del monitor conta come una richiesta API da una regione. I check multi-regione moltiplicano il numero di chiamate – usa la single-region se la tua API ha limiti severi.