Surveillance d'API : quand le code HTTP 200 ne suffit pas

Une API JSON peut renvoyer un code HTTP 200 avec un corps qui décrit une erreur - une surveillance basée sur le code de statut déclarera l'API comme opérationnelle. La vraie surveillance d'API vérifie aussi le contenu de la réponse, pas seulement le HTTP.

Le problème : HTTP 200 ≠ API fonctionnelle

Selon les conventions REST, les codes de statut devraient être utilisés correctement (200 OK, 4xx erreur client, 5xx erreur serveur). En pratique :

Certaines API renvoient toujours 200, l'erreur se trouve dans le corps JSON
Une passerelle d'API (API gateway) peut transformer un 5xx en 200 accompagné d'un JSON d'erreur
Les points d'accès BFF du frontend enveloppent souvent les backends et renvoient 200 si la communication a abouti, même si le backend a échoué
Les points d'accès GraphQL renvoient typiquement 200 ; les erreurs se trouvent dans le champ errors[]

Du point de vue d'une surveillance classique (code de statut HTTP), tout va bien. Du point de vue d'un vrai client, l'API est cassée.

Correspondance de contenu : les mots-clés

Le complément le plus simple à la surveillance HTTP est la correspondance d'un mot-clé. Vous définissez une chaîne qui doit être présente dans la réponse - si elle manque, une alerte est envoyée.

Exemple pour un point d'accès de contrôle de santé (health check) :

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Configurez la correspondance de mot-clé sur "status":"ok". Si la base de données tombe et que le point d'accès renvoie "status":"degraded", la surveillance le détectera.

Correspondance négative : ce qui devrait être absent

Il est parfois plus utile de vérifier qu'une certaine chaîne N'EST PAS présente dans la réponse :

"error" - une erreur dans le corps
"maintenance" - un mode maintenance inattendu
"deprecated" - le point d'accès de l'API a été marqué comme obsolète (deprecated)
des fragments d'erreur SQL : "SyntaxError", "undefined", "null pointer" - des erreurs de backend qui transparaissent

Assertions avancées

La correspondance de texte brut a ses limites. Pour une surveillance d'API sérieuse, on privilégie les assertions structurées sur la structure JSON (expressions JSONPath) et les transactions synthétiques en plusieurs étapes (connexion -> point d'accès protégé -> déconnexion).

ePulz.io prend en charge ces possibilités directement. La surveillance multi-étapes / d'API permet d'enchaîner jusqu'à 10 étapes (GET/POST/PUT/PATCH/DELETE/HEAD), de vérifier à chaque étape le code de statut, le contenu ainsi que la valeur JSONPath, et de stocker des variables issues de la réponse pour les étapes suivantes. La fonction est disponible sur les plans Pro et Business et s'exécute sur la région primaire. Pour des cas plus simples sur les plans inférieurs, vous pouvez combiner un moniteur HTTP avec un script auxiliaire distinct qui envoie le résultat via un moniteur heartbeat.

L'authentification dans la surveillance

Le point d'accès surveillé exige souvent une authentification. Les options :

Jeton Bearer dans l'en-tête Authorization - typiquement un jeton de surveillance à longue durée de vie sans expiration (à stocker en lieu sûr)
Clé d'API dans un paramètre de requête - visible dans les journaux, peu recommandé
Signature HMAC - horodatage + URL + hachage du corps signés avec un secret partagé. Le plus sûr.
mTLS - certificat client côté surveillance. Adapté aux API internes.

Avertissement de sécurité : Pour la surveillance, créez un compte / jeton dédié aux droits minimaux (point d'accès de santé en lecture seule, pas un jeton admin). Faites tourner le jeton régulièrement. Si le service de surveillance fuite, l'accès complet à l'API ne fuite pas.

SLO du temps de réponse

Le temps de réponse de l'API est tout aussi important que le code HTTP. Un client avec un délai d'attente de 30 s ne voit pas la différence entre « l'API renvoie 200 en 25 s » et « l'API a fini par un délai d'attente dépassé ». Du point de vue de l'expérience utilisateur, les deux sont mauvais.

Configurez :

Délai d'attente strict - après 10 à 15 s, la surveillance signale DOWN
Seuil souple - un temps de réponse entre 500 et 2000 ms = avertissement (performance dégradée)
Alertes de tendance - une alerte si le 95e centile du temps de réponse augmente de 50 % au cours des dernières 24 h

Surveillance par point d'accès

Une grande API possède des dizaines de points d'accès. Ne surveillez pas seulement /health - lui aussi peut mentir. Identifiez 3 à 5 points d'accès critiques :

Les opérations métier les plus utilisées (POST /api/orders, GET /api/dashboard)
Un point d'accès en lecture testant un cache hit (réponse rapide)
Un point d'accès en écriture avec un aller-retour en base de données
Un point d'accès d'intégration externe (qui appelle un tiers - détecte les pannes de dépendances)

Surveillez chacun séparément. Lors d'un incident, vous voyez ainsi précisément quelle partie de l'API est tombée.

Conclusion

La surveillance d'API ne peut pas se réduire au code de statut HTTP. Une surveillance de qualité combine statut + correspondance de contenu + temps de réponse + granularité par point d'accès + authentification, afin d'imiter fidèlement un vrai client - et pas seulement un client HTTP.

Surveillance d'API avec correspondance de mot-clé

Code de statut + mot-clé dans le contenu + temps de réponse + en-têtes d'authentification. Granularité par point d'accès.

Lancer la surveillance →