Surveiller une API JSON et détecter les pannes silencieuses
Apprenez à détecter les changements de structure et les chutes de volume d’une API JSON. Découvrez une méthode simple à intégrer dans GitHub Actions.
Votre API répond 200, mais vos données sont-elles encore fiables ?
Un contrôle de disponibilité peut confirmer qu'une API répond. Il ne dit pas si les données reçues sont toujours exploitables. C'est le piège des pannes silencieuses : le serveur renvoie un statut HTTP 200, mais un champ a disparu, un type a changé, ou le flux ne contient plus que quelques éléments. Pour le client HTTP, tout va bien. Pour votre traitement métier, le problème est déjà en production.
Ce risque concerne les équipes qui consomment des offres d'emploi, des données de fournisseurs, des cours boursiers ou tout autre flux JSON public. Une vérification limitée au code de réponse ne détecte ni une dérive de schéma ni une baisse brutale du nombre d'enregistrements. Il faut donc surveiller le contenu, pas seulement la disponibilité du serveur.
Dans cet article, on va voir comment repérer ces anomalies, ce qu'une vérification basée sur une référence peut (et ne peut pas) garantir, et comment intégrer cette surveillance à une chaîne CI. On passera aussi en revue jobfeed-watchdog, un outil en Python sans dépendance externe, ainsi que ses limites avant de l'utiliser en contrôle de production.
Pourquoi un statut HTTP 200 ne suffit pas
Une réponse HTTP 200 signifie que la requête a été traitée avec succès du point de vue du protocole. Elle ne dit pas si le corps contient les bonnes données, ni si celles-ci respectent le contrat attendu par votre application.
Prenons un service qui importe chaque matin des offres d'emploi. Le fournisseur répond toujours, mais le flux passe de 800 annonces à 12. Autre scénario : le champ salary devient compensation, ou bien salary reste présent mais passe d'un nombre à une chaîne de caractères. Le processus de récupération peut se terminer sans erreur, alors que le tableau de bord ne montre plus les salaires ou que la recherche indexe beaucoup moins d'offres.
Dans beaucoup de cas, ce défaut se repère moins facilement qu'une erreur HTTP 500. Une erreur visible déclenche souvent une alerte existante. Une réponse « valide » en apparence, elle, peut passer plusieurs étapes avant que quelqu'un remarque que des données manquent. Et les conséquences dépendent du système : rapports incomplets, décisions basées sur des données obsolètes, factures erronées, ou traitement aval bloqué.
Disponibilité et intégrité : deux questions différentes
Un contrôle de disponibilité répond à une question simple : est-ce que l'endpoint répond ? Un contrôle d'intégrité répond à autre chose : est-ce que la réponse ressemble encore à ce que notre système sait traiter ?
En pratique, il faut souvent les deux. Le premier repère une panne réseau, une indisponibilité du service, ou un temps de réponse anormalement élevé. Le second vérifie les propriétés du contenu qui comptent pour votre usage. Confondre les deux donne une fausse impression de sécurité : une sonde « verte » n'implique pas que le flux métier soit sain.
La même logique vaut pour une API liée au CAC 40, un fournisseur de données, ou un service qui publie des informations autour de l'emploi en France. Les conséquences changent, mais la question reste la même : quelles propriétés de la réponse doivent rester vraies pour que le système aval continue de fonctionner ?
Le coût des vérifications manuelles
Faire une inspection ponctuelle du JSON peut aider au début. Mais ça ne remplace pas une vérification régulière. Les API évoluent, les fournisseurs déploient des changements, et les flux peuvent avoir des incidents temporaires. Le faire « à la main » chaque jour finit par être fragile, et ça ne passe pas à l'échelle.
La bonne approche n'est pas forcément d'ajouter une plateforme de supervision complète. Dans un petit projet, un contrôle automatisé exécuté régulièrement peut suffire à attraper les régressions les plus visibles. L'important est de choisir des contrôles proches de vos usages, puis de les exécuter sans dépendre de la mémoire d'une personne.
Ce qu'il faut surveiller dans une réponse JSON
Une surveillance utile commence par un modèle simple des propriétés à vérifier. Pour repérer les pannes silencieuses dans un flux JSON, trois axes couvrent déjà beaucoup de cas : la structure des objets, le volume d'enregistrements, et l'indisponibilité « totale ».
1. La dérive de schéma
Le schéma décrit la forme des données. Sans aller jusqu'à une validation métier complète, on peut déjà regarder quelles clés sont présentes et le type des valeurs. Par exemple, un objet peut avoir id en nombre, title en chaîne, et location en chaîne ou en valeur nulle.
Les changements à surveiller incluent notamment :
- un champ supprimé alors qu'un traitement l'utilise ;
- un nouveau champ (pas forcément un problème, mais à examiner) ;
- un type modifié, par exemple un nombre remplacé par une chaîne ;
- une structure imbriquée déplacée ou modifiée ;
- un format global qui change, par exemple un tableau remplacé par un objet.
Un champ ajouté n'est pas forcément une régression : c'est souvent une évolution normale. En revanche, si votre application dépend d'un champ qui disparaît, c'est un signal sérieux. L'outil doit donc fournir un diagnostic exploitable, et l'équipe doit décider quels changements nécessitent une action.
2. La chute du nombre d'éléments
Le volume est simple à mesurer, et souvent très parlant. Si un flux fournit d'habitude plusieurs centaines d'enregistrements et n'en renvoie plus soudainement qu'une douzaine, ça mérite une vérification. Une API peut rester accessible alors que la collecte amont est partielle, qu'un filtre a changé, ou que le fournisseur a renvoyé une réponse vide.
Cela dit, une baisse de volume ne prouve pas à elle seule qu'il y a un incident. Le nombre d'offres d'emploi, par exemple, peut varier selon le jour ou la période. La comparaison doit donc se faire par rapport à une référence, en tenant compte des variations « normales ». Sinon, vous aurez soit trop de bruit (alerte sur le moindre écart), soit trop de trous (alerte qui ne se déclenche qu'à zéro).
3. L'indisponibilité complète
Il faut aussi détecter les pannes nettes : absence de réponse, erreur HTTP, délai dépassé, ou corps impossible à lire. La surveillance du contenu complète le contrôle de disponibilité, elle ne le remplace pas. L'idée est de distinguer les erreurs réseau des réponses techniquement correctes mais anormales.
C'est justement la combinaison de ces contrôles qui rend les alertes actionnables. Si tout se résume à « échec » sans détail, le diagnostic demande plus de temps. Savoir si l'API ne répond plus, si le schéma a bougé, ou si le volume a chuté permet souvent de cibler plus vite le fournisseur, le réseau, ou votre traitement.
Mettre en place une surveillance avec jobfeed-watchdog
jobfeed-watchdog, qu'on abrège souvent JFW, est un outil libre fourni sous forme d'interface en ligne de commande et d'une action GitHub. Il interroge une API JSON, examine sa structure et le nombre d'enregistrements, puis compare le résultat à une référence. Son but : remonter des anomalies qu'un simple contrôle de statut HTTP ne verrait pas.
Le projet indique utiliser uniquement la bibliothèque standard de Python. Dit autrement : pas de dépendances Python tierces pour les fonctions de surveillance. En revanche, il faut installer l'outil, et vérifier les conditions d'exécution propres à votre environnement avant de l'intégrer dans votre CI.
Démarrer avec la ligne de commande
L'exemple fourni par le projet est volontairement simple :
pip install jobfeed-watchdog
jobfeed-watchdog https://api.example.com/v1/jobs --baseline baseline.json
La première commande installe le paquet. La seconde demande à l'outil de contrôler l'endpoint et de le comparer à un fichier de référence. Remplacez l'URL d'exemple par la vôtre, puis adaptez la référence à la façon dont votre projet la produit et la conserve. Avant d'automatiser son renouvellement, relisez la documentation du projet : le comportement exact de mise à jour doit être clair.
Et gardez une idée en tête : une référence n'est pas une vérité absolue. C'est un point de comparaison. Si la structure de l'API change volontairement, il faudra analyser le changement et mettre à jour la référence de manière contrôlée. Sinon, vous finirez par comparer la production à une « ancienne version » qui ne correspond plus à ce que vous attendez.
L'intégrer dans une chaîne GitHub Actions
Avec une action GitHub, vous pouvez exécuter un contrôle de façon répétable dans un environnement déjà utilisé par l'équipe. Une exécution planifiée peut surveiller une API même sans nouveau déploiement de votre application. C'est utile quand la dépendance évolue indépendamment de votre code.
Avant d'ajouter quoi que ce soit, clarifiez ces quatre points :
- À quelle fréquence lancer le contrôle ? Une API très changeante peut nécessiter des vérifications plus rapprochées qu'un flux rarement mis à jour.
- Quel environnement ou quelle branche porte la référence ? La référence doit être versionnée ou gérée d'une façon compréhensible pour l'équipe.
- Que se passe-t-il si une anomalie est détectée ? Au début, un simple échec de tâche peut suffire, mais pour un flux critique, une notification dédiée est souvent nécessaire.
- Qui valide une évolution attendue ? Une référence ne doit pas être actualisée automatiquement à chaque différence sans revue.
Les paramètres exacts de l'action et la configuration des déclencheurs dépendent de la documentation du projet. Mieux vaut partir de leurs exemples maintenus que copier une configuration « supposée » : selon les versions, les noms d'entrées et les comportements peuvent évoluer.
Choisir une référence représentative
Une référence construite à partir d'un seul échantillon peut être trompeuse. Si l'API renvoie des champs différemment selon les éléments, un instantané partiel risque de ne pas représenter les cas courants. Pareil pour le volume : une journée atypique peut créer une référence qui déclenche ensuite de fausses alertes.
Idéalement, choisissez une période connue pour être « saine », et vérifiez plusieurs réponses si les données varient. Notez aussi les changements intentionnels, la date de validation et le contexte. Ce mini-historique aide à distinguer une évolution acceptable d'une régression, surtout quand plusieurs personnes touchent au pipeline.
Limites, alertes et bonnes pratiques
Un outil de surveillance ne peut pas « deviner » ce que vos données signifient. Il peut signaler qu'un champ a changé, ou que le volume est inhabituel ; il ne sait pas si une baisse correspond à un jour férié, à une saisonnalité normale, ou à une panne chez le fournisseur. La qualité des alertes dépend donc autant des seuils et du contexte que de la comparaison technique.
Éviter les alertes qu'on finit par ignorer
Si une alerte se déclenche à chaque variation mineure, l'équipe apprend vite à la laisser passer. Or les flux réels évoluent. Un nouveau champ peut s'ajouter sans casser votre consommation. À l'inverse, une chute de volume importante peut être critique même si le schéma ne bouge pas.
Un bon réflexe consiste à classer les changements selon leur impact :
- À examiner : champ ajouté ou évolution inhabituelle sans conséquence immédiate connue ;
- À traiter rapidement : champ attendu absent ou type devenu incompatible ;
- Critique : réponse vide ou chute de volume qui empêche le traitement métier.
Cette classification n'est pas universelle. Une équipe qui utilise uniquement des identifiants n'aura pas les mêmes priorités qu'un service qui calcule des indicateurs à partir des salaires. Le bon seuil correspond au coût d'une donnée erronée, et au coût d'une fausse alerte.
Garder des contrôles métier en complément
La forme et le volume ne prouvent pas que les valeurs sont correctes. Une API peut conserver exactement les mêmes clés et renvoyer des dates incohérentes, des montants mal formatés, ou des identifiants dupliqués. Pour les données qui comptent vraiment, ajoutez des contrôles adaptés : plages de valeurs, unicité, fraîcheur, complétude, ou règles de cohérence entre champs.
Par exemple : un flux de prix peut garder le même schéma tout en renvoyant des valeurs nulles. Un flux d'annonces peut garder un volume stable et répéter les mêmes éléments. L'objectif de JFW est surtout de repérer la dérive de structure, l'effondrement du nombre d'éléments et l'indisponibilité ; il ne faut pas lui demander de faire une validation métier plus large que ce qu'il annonce.
Protéger les données et cadrer le contrôle
Avant d'interroger une API en continu, vérifiez ses conditions d'utilisation, ses limites de débit, et les données incluses dans les réponses. Si le flux contient des données personnelles, le RGPD et vos règles internes de conservation et d'accès restent applicables. Une surveillance technique ne justifie pas de stocker inutilement des réponses complètes, ni des informations sensibles dans les journaux de CI.
Enfin, une tâche GitHub Actions n'est pas, à elle seule, une astreinte. Si le contrôle est important, assurez-vous que les échecs sont bien vus : notifications, responsabilités claires, et procédure de diagnostic. Une tâche qui échoue sans être consultée ne protège pas réellement la production.
Quand passer à une solution plus complète
Un outil léger est pertinent quand votre besoin est ciblé et que vous évitez d'ajouter une plateforme à maintenir. Si vous surveillez quelques API publiques et que vous voulez repérer des régressions simples dans CI, une commande autonome peut suffire.
En revanche, plusieurs besoins justifient un système plus large : historique de métriques, tableaux de bord, gestion de seuils complexes, notifications multi-canaux, contrôles métier plus avancés, ou supervision de nombreux fournisseurs. Tout dépend du coût d'exploitation et du niveau de criticité. Et non : la solution « la plus élaborée » n'est pas forcément la plus fiable si personne ne sait la configurer ni interpréter ses alertes.
Conclusion - Surveillez les données qui comptent
Un contrôle HTTP classique vous dit si le serveur répond. Il ne vous dit pas si votre flux JSON contient encore les champs attendus, si son volume reste plausible, ou si vos traitements en aval peuvent continuer sans produire de résultats incomplets. C'est ce décalage qui rend les pannes silencieuses si difficiles à détecter.
Commencez par identifier les propriétés vraiment importantes pour votre produit : structure, volume, fraîcheur, et règles métier. Automatisez les contrôles adaptés, gardez une référence compréhensible, et définissez qui examine les alertes. jobfeed-watchdog peut être un bon point de départ pour surveiller un endpoint depuis la ligne de commande ou GitHub Actions ; il ne remplace pas des validations métier, ni une supervision dimensionnée pour un service critique.
Si vous consommez une API publique en production, listez dès maintenant les deux ou trois anomalies qui auraient le plus d'impact chez vous. Puis ajoutez un contrôle automatisé pour chacune. L'objectif n'est pas de tout surveiller : c'est de repérer une donnée cassée avant que vos utilisateurs, ou vos équipes, ne s'en aperçoivent.