Documentazione

Monitoraggio API: controllare JSON, XML, HTML e header

Un server che risponde 200 OK con una pagina di errore, una lista vuota o i dati di ieri è online secondo qualsiasi controllo del codice di stato, ma non funziona per nessuno di coloro che lo usano. Per questo Pingsured può verificare cosa contiene una risposta, non solo che sia arrivata.

Tutti i controlli descritti qui sotto sono facoltativi e puoi combinarli liberamente. Un ping supera il controllo solo quando il codice di stato corrisponde e tutti i controlli del contenuto che hai configurato hanno esito positivo.

Codice di stato

Il codice di stato atteso può essere un singolo codice, un elenco o un intervallo: 200, 200,204 oppure 200-299. Qualsiasi altro valore è un errore. Il valore predefinito è 200.

Testo nel corpo della risposta

Il controllo del contenuto più semplice: il corpo della risposta deve contenere un certo testo, per esempio il nome di un prodotto o l'indicatore «tutto ok» che restituisce il tuo endpoint di health check. Si tratta di una semplice ricerca di sottostringa, fino a 1.024 caratteri.

Campi JSON (JSONPath)

Per le API, selezioni un valore con un'espressione JSONPath e lo confronti. Per esempio, un endpoint di health check che risponde {"status": "ok", "queue": {"depth": 12}} si può monitorare così:

Operatori disponibili:

• esiste / non esiste — il percorso seleziona qualcosa, oppure niente.
• uguale a / diverso da — con il tipo: il numero 12 non è uguale alla stringa "12".
• contiene e corrisponde a (un'espressione regolare) per il testo.
• maggiore / minore di (o uguale) per i numeri.
• confronti sul numero di corrispondenze, come «almeno un elemento in $.items[*]».
• confronti sull'età per i timestamp, descritti più avanti nella sezione sull'attualità dei dati.

Quando un percorso seleziona più valori, viene confrontato il primo. Fino a 16 controlli JSON per ping.

Elementi XML (XPath)

Lo stesso principio per le risposte XML — feed, servizi SOAP, sitemap — con espressioni XPath come /rss/channel/item (almeno 1 corrispondenza) o //status/text() (uguale a ok). Gli operatori sono esiste, non esiste, uguale a, contiene, corrisponde a, i confronti sul numero e quelli sull'età. Una risposta che non è XML ben formato fa fallire tutti i controlli XML.

Elementi HTML (selettori CSS)

Per le pagine web, scegli un elemento con un selettore CSS — oppure con un'espressione XPath, se preferisci — e controlli il suo testo o uno dei suoi attributi. Il testo viene confrontato con gli spazi normalizzati, quindi gli a capo nel markup non contano. Usi tipici:

• l'elemento del prezzo in una pagina prodotto esiste e non è vuoto;
• h1.title contiene il tuo titolo, così ti accorgi di un template vuoto o di una pagina di manutenzione;
• l'attributo content di un tag meta ha il valore previsto.

Header della risposta

Gli header si possono controllare in due modi: con una corrispondenza esatta per ciascun header, oppure con gli stessi operatori visti sopra (esiste, non esiste, uguale a, contiene, corrisponde a, confronti numerici ed età). I controlli sugli header non leggono il corpo della risposta.

Attualità: i dati sono aggiornati?

Gli operatori sull'età leggono un valore come timestamp e ne confrontano l'età, in secondi. «$.updated_at età minore di 3600» fallisce non appena i dati più recenti hanno più di un'ora — il caso tipico di un export, una cache o un feed che ha smesso di aggiornarsi senza far rumore, mentre il server continua a rispondere.

Formati riconosciuti:

• ISO 8601 / RFC 3339, come 2026-10-09T14:30:00Z (un orario privo di fuso orario viene letto come UTC);
• date HTTP, quindi un header Last-Modified funziona così com'è;
• Unix time in secondi o in millisecondi.

Limiti da conoscere

• Il corpo della risposta viene letto fino a 1 MB.
• I controlli inviano richieste GET o HEAD. Altri metodi e corpi della richiesta non sono ancora disponibili: possono modificare dati sul server controllato, quindi richiederanno prima la verifica che il dominio sia tuo.
• Puoi aggiungere fino a 20 header della richiesta e l'autenticazione HTTP basic, per gli endpoint che richiedono un token o un login.
• Lo user agent è sempre Pingsured/1.0, con un link alla pagina che spiega le nostre richieste a chi gestisce i server.