La risposta dell’endpoint incidents di UptimeScout basta per annunciare subito un’interruzione del servizio? No: questo endpoint elenca i servizi con segnali elevati di disservizio rilevati di recente e la specifica precisa che non si tratta di incidenti confermati dal provider. Il risultato pratico è un breve elenco di segnali da verificare, non una conclusione già pronta sulla causa dell’interruzione.

È una distinzione utile per chi è di turno e per gli analisti: un avviso automatico può dire «controllare il servizio X nella regione Y», lasciando la conferma del fatto e la spiegazione della causa allo stato ufficiale del provider o alla diagnostica interna. La specifica di UptimeScout documenta endpoint separati per i segnali, lo stato attuale e la cronologia delle osservazioni.
Che cosa restituisce l’elenco dei segnali
/v1/incidents è un endpoint GET che elenca i servizi con segnali elevati di disservizio. I parametri includono filtri per servizio, regione, categoria, termine di ricerca e intervallo temporale. La risposta richiede una licenza; l’API descrive l’autenticazione tramite token Bearer. Il campo della regione accetta un codice di due lettere e hours definisce un intervallo da 1 a 2160 ore.
È facile interpretare «incident» nell’URL come «interruzione confermata», ma la documentazione gli attribuisce un significato più circoscritto: un segnale recente basato sulle osservazioni. Perciò è meglio formulare l’avviso sulla base dei dati restituiti, per esempio «è stato rilevato un segnale di problemi di disponibilità», senza attribuire al fornitore del servizio la conferma di un incidente.
Controlli minimi prima di inviare un avviso
Per prima cosa, salva la risposta originale insieme all’ora di ricezione e ai parametri della richiesta. Poi controlla quali servizio e regione sono stati restituiti e valuta l’attualità usando i campi del servizio observed_at e stale. Se l’osservazione è contrassegnata come obsoleta, va distinta dal segnale attuale, anziché essere mostrata come stato «in questo momento».
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Questo esempio effettua una richiesta per gli Stati Uniti con un intervallo di 24 ore; la chiave viene letta da una variabile d’ambiente e non viene mostrata nella riga di comando. Dopo aver ricevuto la risposta, controlla gli errori HTTP e la struttura JSON, quindi elabora separatamente ciascun servizio restituito. I valori di stato previsti dallo schema includono operational, degraded, outage e unknown; se un campo o un valore è assente, non sostituirlo con una tua interpretazione.
Per un segnale che richiede un intervento, recupera lo stato attuale del servizio corrispondente tramite /v1/status e la cronologia tramite /v1/history. Nella cronologia è utile conservare, insieme alle serie, resolution_seconds, samples, counts ed effective_start: così l’analista può vedere con quale granularità temporale sono stati raccolti i dati e per quale intervallo effettivo sono disponibili. La specifica avverte che gli intervalli mancanti sono sconosciuti; un intervallo vuoto non va considerato automaticamente né come disponibilità né come interruzione.
Come trasformare la risposta in un rapporto verificabile
Per ogni voce, registra i campi seguenti: identificativo e nome del servizio, regione della richiesta, stato, ora dell’osservazione, indicatore di obsolescenza, ora di ricezione della risposta e link alla fonte dello stato ufficiale, se il team l’ha verificato. Quest’ultimo campo viene compilato dalla tua integrazione o da un operatore: la specifica di UptimeScout non garantisce che il segnale includa una causa confermata o una dichiarazione del provider.

Dividi il flusso di lavoro in tre stati. «Segnale ricevuto» significa che la voce è comparsa nei risultati di /v1/incidents. «Verifica dello stato in corso» significa che hai richiesto lo stato attuale e la cronologia. Riserva «confermato» a una conclusione sostenuta da una comunicazione ufficiale esterna o da una verifica interna. Questa semplice distinzione impedisce alla dashboard di presentare un segnale aggregato come un fatto accertato.
Se il team crea rapporti per più regioni, esegui richieste separate con i codici regionali necessari e salva il parametro insieme al risultato. Il campo lang riguarda la lingua delle descrizioni dei servizi, non modifica la regione delle osservazioni. Questa distinzione è importante, per esempio, quando si confrontano un catalogo localizzato e uno stato regionale.
Dove si fermano le conclusioni
Il risultato verificabile di questo flusso è un registro dei segnali con indicazioni esplicite di orario, regione e attualità, completato da una verifica separata dello stato e della cronologia. Aiuta a individuare che cosa richiede attenzione e che cosa è stato possibile confermare consultando le fonti scelte. La risposta di /v1/incidents segnala un livello elevato di osservazioni; per annunciare un’interruzione confermata servono dati di conferma.