Peut-on annoncer immédiatement une panne de service à partir de la réponse UptimeScout incidents ? Non : cet endpoint répertorie les services ayant récemment présenté des signaux élevés de perturbation, et la spécification précise qu’il ne s’agit pas d’incidents confirmés par le fournisseur. En pratique, on obtient une courte liste de signaux à vérifier, pas une conclusion toute faite sur la cause de la panne.

Cette distinction est utile à l’ingénieur d’astreinte comme à l’analyste : une alerte automatisée peut dire « vérifiez le service X dans la région Y », tout en laissant la confirmation du fait et l’explication de sa cause au statut officiel du fournisseur ou à votre propre diagnostic. La spécification UptimeScout documente des routes distinctes pour les signaux, le statut actuel et l’historique des observations.
Ce que renvoie exactement la liste de signaux
/v1/incidents est un endpoint GET qui répertorie les services présentant des signaux élevés de perturbation. Ses paramètres permettent de filtrer par service, région, catégorie, terme de recherche et fenêtre temporelle. La réponse nécessite une licence ; l’API décrit une authentification par jeton Bearer. Le champ de région accepte un code à deux lettres, et hours définit une fenêtre comprise entre 1 et 2160 heures.
Le mot « incident » dans le chemin peut facilement être interprété comme « panne confirmée », mais la documentation lui donne un sens plus restreint : un signal récent issu des observations. Il convient donc de formuler la notification en fonction des données de la réponse, par exemple « un signal de perturbation de la disponibilité a été reçu », sans attribuer au fournisseur de service la reconnaissance d’un incident.
Vérification minimale avant d’envoyer une notification
Commencez par enregistrer la réponse brute, ainsi que l’heure de réception et les paramètres de la requête. Vérifiez ensuite le service et la région renvoyés, puis évaluez la fraîcheur à l’aide des champs du service observed_at et stale. Si l’observation est signalée comme obsolète, distinguez-la d’un signal actuel au lieu de l’afficher comme l’état « en ce moment ».
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Voici un exemple de requête portant sur les États-Unis et une fenêtre de 24 heures ; la clé est lue depuis une variable d’environnement et n’apparaît pas dans la ligne de commande. Après réception de la réponse, vérifiez les erreurs HTTP et la structure JSON, puis traitez séparément chaque service renvoyé. Les valeurs de statut définies dans le schéma comprennent operational, degraded, outage et unknown ; si un champ ou une valeur manque, ne lui substituez pas votre propre interprétation.
Pour un signal nécessitant une action, demandez le statut actuel du service concerné via /v1/status et son historique via /v1/history. Dans l’historique, il est utile de conserver à côté des séries resolution_seconds, samples, counts et effective_start : l’analyste peut ainsi voir la granularité temporelle des données et l’intervalle réellement couvert. La spécification avertit que les intervalles manquants sont inconnus ; un intervalle vide ne peut pas être automatiquement considéré comme une période de disponibilité ou de panne.
Transformer la réponse en rapport vérifiable
Pour chaque entrée, créez les champs suivants : identifiant et nom du service, région de la requête, statut, heure d’observation, indicateur d’obsolescence, heure de réception de la réponse et lien vers la source officielle du statut, si l’équipe l’a vérifiée. Ce dernier champ est renseigné par votre intégration ou votre opérateur : la spécification UptimeScout ne garantit pas que le signal contienne une cause confirmée ou une déclaration du fournisseur.

Divisez le processus en trois états. « Signal reçu » signifie que l’entrée figure dans le résultat de /v1/incidents. « Statut en cours de vérification » signifie que vous avez demandé l’état actuel et l’historique. Réservez « confirmé » à une conclusion étayée par une communication officielle externe ou une vérification interne. Cette séparation simple empêche le tableau de bord de présenter un signal agrégé comme un fait établi.
Si l’équipe produit un rapport couvrant plusieurs régions, effectuez des requêtes distinctes avec les codes de région nécessaires et enregistrez chaque paramètre avec son résultat. Le champ lang concerne la langue des descriptions des services ; il ne modifie pas la région des observations. Cette distinction est importante pour comparer, par exemple, un catalogue localisé et un état régional.
Où s’arrête la conclusion
Le résultat vérifiable de ce scénario est un journal des signaux comportant des horodatages, des régions et des indicateurs de fraîcheur explicites, complété par une vérification distincte du statut et de l’historique. Il aide à repérer ce qui nécessite une attention particulière et ce qui a pu être confirmé à partir des sources choisies. La réponse de /v1/incidents indique un signal d’observation élevé ; des données à l’appui sont nécessaires pour annoncer une panne confirmée.