Surveiller une API, c’est appeler une route réelle depuis l’extérieur et juger la réponse : le code, le temps, et un morceau du contenu. Un ping sur le nom d’hôte ne dit pas qu’une route métier répond. Un simple « le port 443 est ouvert » non plus. Le contrôle doit échouer quand un client de l’API échouerait.
Ce n’est pas la même chose que surveiller l’écran d’une application. L’API peut être verte et la page de connexion cassée, ou l’inverse. Le parcours côté navigateur est décrit dans le monitoring d’une application SaaS. Ici, on parle des routes HTTP que d’autres programmes appellent.
Choisir une route qui prouve quelque chose
La route de contrôle est une lecture, répétable, qui touche les mêmes dépendances que le service utile. Si les clients lisent des dossiers en base, un contrôle qui ne fait que renvoyer un fichier statique {"ok": true} ne voit pas une base arrêtée.
| Contrôle | Ce qu’il prouve | Ce qu’il ne prouve pas |
|---|---|---|
| TCP ou ping | La machine répond au réseau | Qu’une route métier fonctionne |
GET /health minimal | Le processus HTTP tourne | La base, le cache, un tiers |
GET d’une ressource de test | Code, délai, forme du JSON | Les routes qu’on n’appelle pas |
Écriture POST répétée | À éviter | Vous polluez les données |
Fixez le résultat attendu : code 200, et un champ JSON présent (status égal à ok, ou un identifiant de jeu de test non vide). Un code 200 avec un corps {"error": "unavailable"} est une panne si vos clients le traitent comme tel. Écrivez le critère comme le client le lirait.
Le délai se règle à partir du temps habituel de cette route, pas d’un chiffre universel. Si la route répond d’ordinaire en moins de 300 ms, un seuil d’alerte à plusieurs secondes détecte un blocage. Un seuil plus court que le temps normal déclenche des alertes les jours de charge. Notez le seuil à côté de la route pour que le prochain réglage ne parte pas de zéro.
Authentification et effets de bord
Le contrôle s’authentifie avec un jeton dédié, aux droits minimaux, sur un compte ou un tenant de test. Il ne réutilise pas la clé d’un client, ni un jeton d’administration. Quand vous faites tourner les secrets, mettez à jour la sonde en même temps, sinon vous surveillez une 401 que vous venez de créer.
N’appelez pas en boucle :
- la création de commande, de compte ou de paiement ;
- l’envoi d’e-mail ou de SMS ;
- une route qui compte dans la facturation à l’appel ;
- une recherche tellement lourde qu’elle dégrade l’API pour les vrais clients.
Si la seule façon de « voir si ça marche » est un POST, faites-le rares fois, sur la recette, pas chaque minute en production. En production, une lecture d’une ressource de test suffit. Espacez les appels pour rester sous les quotas : une sonde trop nerveuse se fait limiter, puis vous alertez sur votre propre blocage. Le même phénomène côté pages est décrit pour les requêtes HTTP trop nombreuses.
Depuis l’extérieur du réseau où tourne l’API, le contrôle voit aussi le DNS, le certificat et le pare-feu. Une sonde installée sur le même serveur que l’API reste verte quand plus personne ne la joint. Un service comme le monitoring SiteGarde joue ce rôle pour une URL ou une route exposée. Les routes purement internes, sans accès depuis Internet, se contrôlent depuis le réseau privé, pas en les ouvrant au monde pour les surveiller.
Quand l’alerte part
Alertez après plusieurs échecs de suite, en distinguant le délai dépassé, le 5xx et le corps inattendu. Les trois n’ont pas la même cause. Le message contient la route, le code, le temps de réponse et l’heure, pas seulement « API down ».
Une 401 apparue après une rotation de jeton est une panne de la sonde, à corriger tout de suite pour ne pas masquer une vraie 500 le lendemain. Une 429 dit que vous appelez trop, ou qu’un client le fait : ce n’est pas la même fiche d’incident qu’une 503.
Revoyez la route de contrôle quand vous ajoutez une dépendance. Un health qui n’a pas été mis à jour après le branchement d’un nouveau fournisseur de paiement reste vert pendant que ce fournisseur est injoignable. La sonde ne devine pas ce que vous avez oublié de lui faire lire.