Monitorare un’API significa inviarle richieste reali a intervalli regolari e verificare che le risposte siano corrette, non solo che il server abbia risposto. Un’API che restituisce 200 OK con una lista vuota, un messaggio di errore nel corpo o una risposta che arriva dopo dieci secondi è rotta per le app che ne dipendono, anche se un controllo semplice risulterebbe superato. Questa checklist spiega cosa configurare perché i tuoi monitor delle API intercettino i problemi reali.
1. Scegli gli endpoint
Non monitorare tutto. Monitora ciò da cui dipendono utenti e integrazioni:
Endpoint di health o di stato, se verifica dipendenze come il database. Un endpoint di health che restituisce solo “ok” senza controllare nulla ti dice poco.
Autenticazione: l’endpoint che emette i token o convalida le sessioni. Se si guasta, si guasta tutto.
Endpoint di lettura principali: quelli che la tua app chiama a ogni schermata, come l’elenco degli ordini o il recupero di un profilo.
Percorsi di scrittura critici: checkout, registrazione o ricevitori di webhook, monitorati con dati di test. Un monitor di flusso esegue una sequenza di chiamate API passo dopo passo, porta valori come un token o l’ID di un ordine da un passo al successivo e mantiene protetti i segreti.
API di terze parti da cui dipendi, come provider di pagamento o di spedizione, così sai quando il problema non è tuo. Il monitoraggio dei servizi di terze parti di Uptimecheck segue le pagine di stato di 31 servizi come Klarna, Shopify e Cloudflare, oppure qualsiasi pagina ospitata su Statuspage.
2. Imposta la richiesta: metodo, header e corpo
Un controllo dovrebbe somigliare alla richiesta di un client reale:
Metodo: GET per le letture, POST, PUT o PATCH per gli endpoint che li richiedono.
Header: Accept: application/json, un Content-Type per le richieste con corpo e gli eventuali header personalizzati richiesti dalla tua API, come un header di versione.
Corpo: un payload piccolo e valido per le richieste POST, per esempio una query di ricerca.
Scegli richieste che si possono ripetere ogni minuto senza rischi. Evita gli endpoint che creano ordini reali, inviano email o addebitano carte, a meno che tu non usi un account di test dedicato.
3. Gestisci l’autenticazione
La maggior parte delle API richiede credenziali. Le opzioni:
Basic auth per endpoint protetti in modo semplice.
API key o bearer token in un header, per esempio Authorization: Bearer <token>.
Crea un account o un token dedicato al monitoraggio con permessi di sola lettura. In questo modo limiti i danni se il token trapela e tieni separato nei log il traffico di monitoraggio. Ricorda che i token scadono. Un token di sola lettura a lunga durata per il monitoraggio evita falsi allarmi quando scade un token a breve durata.
4. Verifica il codice di stato
Decidi quali codici di stato indicano un successo. Di solito sono 200, 201 o 204, a seconda dell’endpoint. Fai attenzione ai redirect: un’API che all’improvviso reindirizza a una pagina di login restituisce un 3xx e poi un 200 con HTML. Per qualsiasi app che si aspetta JSON è un’interruzione.
5. Verifica il contenuto della risposta
È qui che la maggior parte dei controlli sulle API si ferma troppo presto. Verifica che la risposta contenga qualcosa che solo un’API funzionante restituirebbe:
Un campo che dovrebbe essere sempre presente, come “status”:”ok” o “id”.
Un valore noto dai dati di test.
L’assenza di testo di errore, come “error”.
Con Uptimecheck imposti per ogni monitor di API i codici di stato attesi, una parola chiave e controlli JSON, per esempio che $.status sia uguale a ok o che un header esista, insieme a metodo, header (inclusi basic auth o bearer token) e corpo.
6. Imposta le soglie del tempo di risposta
Per le API, lento è il nuovo down. Le app mobile vanno in timeout e le integrazioni riprovano, aggiungendo altro carico. Registra il tempo di risposta a ogni controllo e imposta una soglia basata su ciò che è normale:
Osserva una settimana di tempi di risposta per trovare il valore di riferimento.
Imposta una soglia di avviso ben al di sopra della variazione normale, per esempio da due a tre volte il tempo di risposta abituale.
Invia avvisi sulla lentezza prolungata, non sui picchi isolati. Una richiesta lenta è rumore, una serie di richieste lente è un problema.
In Uptimecheck imposti un limite di risposta lenta per ogni monitor e ricevi un avviso di lentezza quando tre controlli di fila sono più lenti del limite, e un altro quando la risposta torna veloce.
Controllare da più di una regione mostra se la lentezza è globale o limitata a un solo percorso di rete. Uptimecheck controlla da Stoccolma, Londra e New York e suddivide ogni tempo di risposta in DNS, connessione, TLS, server e download, così puoi vedere quando inizia la lentezza e dove va il tempo.
7. Monitora l’intera catena
Raramente un’API si guasta da sola. Aggiungi monitor per ciò da cui dipende:
Certificati SSL sull’hostname dell’API. Un certificato scaduto blocca tutti i client in una volta.
Record DNS del dominio dell’API.
Risorse dei server come CPU, memoria e disco dei server dell’API.
Job pianificati che mantengono aggiornati i dati, con gli heartbeat.
8. Indirizza gli avvisi alle persone giuste
Gli avvisi sulle API spettano di solito agli sviluppatori responsabili del servizio. Inviali al canale chat del team e, per le interruzioni in produzione di notte, a un canale che arrivi al telefono. Usa i webhook per inoltrare gli avvisi ai tuoi strumenti di gestione degli incidenti. Vedi notifiche.
9. Automatizza la creazione dei monitor
Se rilasci spesso nuovi servizi, crea i monitor come parte del deploy. La REST API di Uptimecheck (Professional e Business) copre monitor, finestre di manutenzione e aggiornamenti di stato, ed è documentata su app.uptimecheck.com/docs/api, così il monitoraggio può far parte della tua pipeline invece di essere un passaggio manuale successivo. Un server MCP permette agli assistenti AI di fare lo stesso con una API key.
10. Informa chi usa la tua API
Se altri team o clienti sviluppano sulla tua API, offri loro una pagina di stato con un componente dedicato all’API. Eviterà che passino la tua interruzione a fare debug del proprio codice.
Errori comuni nel monitoraggio delle API
Controllare solo l’endpoint di health. Gli endpoint di health spesso risultano ok mentre gli endpoint reali falliscono perché una dipendenza è down.
Usare le credenziali di produzione di un utente reale. Quando quell’utente cambia password o se ne va, il monitoraggio si rompe. Usa un account dedicato.
Ignorare il corpo della risposta. Una pagina di errore HTML con stato 200 supera un controllo basato solo sullo stato.
Inviare avvisi per ogni risposta lenta. I picchi isolati creano rumore e abituano le persone a ignorare gli avvisi.
Dimenticare le dipendenze. L’API funziona, ma il certificato è scaduto o il record DNS è cambiato.
La checklist
Scegli gli endpoint: health, autenticazione, letture principali, scritture critiche, API di terze parti chiave.
Imposta metodo, header e corpo per ogni controllo.
Usa un token dedicato di sola lettura o credenziali basic auth.
Definisci i codici di stato attesi.
Verifica il contenuto: un campo o un valore che solo un’API funzionante restituisce.
Registra il tempo di risposta e invia avvisi sulla lentezza prolungata.
Controlla da più di una regione.
Monitora SSL, DNS, server e job pianificati dietro l’API.
Indirizza gli avvisi al team responsabile, con un canale adatto al telefono per la produzione.
Crea i monitor tramite l’API come parte dei deploy.
In sintesi
Un 200 OK è l’inizio di un controllo sulle API, non la fine. Invia richieste realistiche, verifica il contenuto, tieni d’occhio il tempo di risposta e copri la catena dietro l’API.
Il monitoraggio delle API con metodi, header e corpi personalizzati, controlli JSON e avvisi di risposta lenta è incluso in ogni piano Uptimecheck. Provalo gratis per 14 giorni, senza carta di credito.