Documentazione

Sapere che la tua API risponde bene, non solo che risponde

Per un controllo del codice di stato, la maggior parte dei guasti di un'API non sembra affatto un guasto. Il framework intercetta l'eccezione e risponde 200 OK con {"error": "database unavailable"}. Un import non riuscito lascia vuoto l'elenco dei prodotti. Una cache continua a servire i dati di prima che si fermasse il job che la riempie. In tutti questi casi l'API risulta «online», eppure non funziona per nessuno dei client che la chiamano.

Pingsured legge il JSON della risposta e controlla i valori che ti dicono se l'API sta davvero funzionando.

Cosa controllare

Il punto di partenza più semplice è un endpoint di health check che riporta lo stato delle sue dipendenze. Se risponde {"status": "ok", "db": "ok", "queue": {"depth": 12}}:

L'ultima riga è quella che un codice di stato non potrà mai darti: l'API è online e il lavoro che c'è dietro non si sta accumulando.

Per un endpoint che restituisce dati anziché uno stato, controlla la forma dei dati stessi:

Una lista vuota, un prezzo pari a zero e una risposta più vecchia di quindici minuti fanno fallire il ping, mentre il server continua a rispondere 200.

Endpoint che richiedono credenziali

Aggiungi gli header che l'API si aspetta — un token Authorization: Bearer, un header con la chiave API — oppure l'autenticazione HTTP basic. Dai al controllo un token tutto suo, con permessi di sola lettura: viene salvato insieme al ping, e un token creato per il monitoraggio si può revocare senza rompere nient'altro.

Perché controllare la tua API con Pingsured

• Confronti tipizzati. Il numero 12 non è uguale alla stringa "12": una modifica alla serializzazione che trasforma i numeri in stringhe — e manda in errore ogni client fortemente tipizzato — fa fallire il controllo invece di passare inosservata.
• Attualità dei dati senza script. Gli operatori sull'età leggono timestamp ISO 8601, date HTTP e Unix time, quindi «i dati hanno meno di un'ora» è una riga, non un cron job da monitorare a sua volta.
• Fino a 16 controlli JSON per ping, combinabili liberamente con il codice di stato, un controllo sugli header e una ricerca di testo. Il ping risulta OK solo se passano tutti.
• Controlli da dove si trovano i tuoi client. Ogni località viene valutata per conto suo, quindi un'API che fallisce dietro un nodo CDN o da una regione non viene nascosta dalle altre.
• Avvisi dove lavori. Email e app per impostazione predefinita; dal piano Team in su, un webhook verso il tuo strumento di gestione degli incidenti o la tua chat.
• I dati della tua API restano nell'UE. Endpoint, header e token fanno parte di ciò che un account di monitoraggio conserva. Pingsured li conserva in Germania e Finlandia, senza alcun servizio statunitense lungo il percorso.

Limiti da tenere presenti

• I controlli inviano GET o HEAD. Un'API raggiungibile solo con POST — la maggior parte delle configurazioni GraphQL, SOAP — per ora non si può controllare.
• Ogni controllo è una singola richiesta. Un flusso che prima esegue il login e poi chiama l'API con la sessione ottenuta non è possibile; un token di lunga durata in un header sì.
• Viene letto solo il primo MB della risposta, e un JSON troncato in quel punto non è più valido. Punta il controllo su un endpoint piccolo o su una pagina di un elenco, non su un export completo.