Monitoring d'API : comment vérifier la réponse JSON, pas seulement HTTP 200

En bref : Une API JSON peut renvoyer HTTP 200 avec un corps {"status":"error","message":"DB unavailable"} - un monitoring qui ne surveille que le code de statut annonce "UP". Un vrai monitoring d'API vérifie aussi le contenu de la réponse, pas seulement la couche HTTP.

Le problème : HTTP 200 != API fonctionnelle

Les conventions REST API disent d'utiliser correctement les codes de statut (200 OK, 4xx client error, 5xx server error). En pratique :

• Certaines API renvoient toujours 200, l'erreur est dans le body JSON
• Une API gateway peut transformer 5xx en 200 avec un JSON d'erreur
• Les endpoints frontend BFF wrappent souvent les backends et renvoient 200 si la communication a eu lieu, même si le backend a échoué
• Les endpoints GraphQL renvoient toujours 200, les erreurs sont dans le champ errors[]

Du point de vue du monitoring classique (code de statut HTTP) tout va bien. Du point de vue du vrai client l'API est cassée.

Content matching : mots-clés

Le complément le plus simple au monitoring HTTP est le keyword match. Vous définissez une chaîne qui doit être dans la réponse - si elle manque, alerte.

Exemple pour un endpoint health check :

GET /api/health HTTP/1.1

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

Régler le keyword match sur "status":"ok". Si la DB tombe et que l'endpoint renvoie "status":"degraded", le monitoring attrape.

Negative matching : ce qui devrait manquer

Parfois il est plus utile de vérifier qu'une certaine chaîne N'EST PAS dans la réponse :

• "error" - erreur dans le body
• "maintenance" - mode maintenance inattendu
• "deprecated" - endpoint API devenu deprecated
• fragments d'erreurs SQL : "SyntaxError", "undefined", "null pointer" - erreurs backend qui fuient

Assertions avancées - roadmap

Le match en texte brut a des limites. Pour un monitoring API sérieux, des assertions structurées sur la structure JSON (expressions JSONPath) et des transactions synthétiques multi-étapes (login -> endpoint protégé -> logout) sont appropriées.

Les assertions JSONPath et les transactions synthétiques multi-étapes sont sur la roadmap ePulz.io mais ne sont actuellement pas implémentées. Si vous en avez besoin aujourd'hui, combinez un moniteur HTTP ePulz.io avec votre propre script qui envoie le résultat via un moniteur heartbeat (en cas d'échec, n'envoyez simplement pas le heartbeat).

Authentification dans le monitoring

L'endpoint surveillé exige souvent une auth. Options :

• Bearer token dans le header Authorization - typiquement un token de monitoring long-lived sans expiration (à stocker en sécurité)
• Clé API en paramètre query - visible dans les logs, pas préféré
• Signature HMAC - timestamp + URL + hash du body signé avec secret partagé. Plus sûr.
• mTLS - cert client côté monitoring. Adapté aux API internes.

Avis de sécurité : Pour le monitoring créez un compte / token dédié avec des droits minimaux (endpoint health en lecture seule, pas un token admin). Faites tourner le token régulièrement. Si le service de monitoring fuit, tout l'accès à l'API ne fuit pas.

Response time SLO

Le response time de l'API est aussi important que le code HTTP. Un client avec timeout 30 s ne voit pas la différence entre "l'API renvoie 200 en 25 s" et "l'API a timeouté". Du point de vue UX les deux sont mauvais.

Configurez :

• Hard timeout - après 10-15 s le monitoring annonce DOWN
• Soft threshold - response time entre 500-2000 ms = warning (degraded performance)
• Trending alerts - alerte si le 95ème percentile du response time monte de 50% sur les 24 dernières heures

Monitoring par endpoint

Une grosse API a des dizaines d'endpoints. Ne monitorez pas que /health - même lui peut mentir. Identifiez 3-5 endpoints critiques :

• Opérations business les plus utilisées (POST /api/orders, GET /api/dashboard)
• Endpoint read pour cache hit (réponse rapide)
• Endpoint write avec roundtrip DB
• Endpoint d'intégration externe (appelle un tiers - détecte les pannes des dépendances)

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

Conclusion

Le monitoring d'API ne peut pas être réduit au code de statut HTTP. Un monitoring de qualité combine statut + content match + response time + granularité par endpoint + authentification, pour ressembler à un vrai client - pas seulement un client HTTP.

Monitoring d'API avec keyword match

Code de statut + keyword dans le contenu + response time + auth headers. Granularité par endpoint.

Essayer pendant 7 jours →