Surveillance d'API

Pourquoi une API a besoin de son propre monitoring

Une API n’est pas simplement une page sur /api/. C’est un contrat. La méthode HTTP a de l’importance – GET vs POST change la sémantique. Les headers sont porteurs d’authentification, de négociation de contenu, de clés d’idempotence. Le corps de la requête est l’entrée. Le code de réponse est important (401 vs 403 vs 422 – chacun raconte une histoire différente). Le body de la réponse a une structure – des chemins JSON sur lesquels les intégrateurs comptent. Un simple check uptime qui ne fait qu’un GET sur l’URL passe à côté de la plupart des manières dont une API peut tomber : un JSON invalide renvoyant tout de même un 200, un endpoint d’authentification acceptant de mauvaises données, un webhook à la structure du payload cassée, un endpoint répondant 200 mais contenant "status": "error" dans la réponse.

Le monitoring API résout cela en vous donnant le contrôle sur chaque partie de la requête et sur chaque partie de la validation de la réponse. Vous configurez exactement l’appel tel que fait par vos intégrateurs : même méthode, mêmes headers, même body, même authentification – et ce qui définit précisément le succès : codes exacts, valeurs sur les chemins JSON, seuils de temps de réponse, limites de taille.

Configuration de la requête

Pour chaque moniteur API dans DiagnoSEO Uptime Monitoring, vous pouvez configurer :

• Méthode HTTP : GET, POST, PUT, PATCH, DELETE, HEAD. Choisissez celle qui est utilisée par vos intégrateurs.
• Headers personnalisés : sous forme d’objet JSON, par ex. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standard pour tester OAuth, JWT, clés API, negotiation de contenu.
• Corps de la requête : n’importe quelle chaîne – JSON, XML, form-encoded, texte simple. Envoyé pour POST/PUT/PATCH/DELETE.
• Authentification de base : utilisateur et mot de passe, si le endpoint est ainsi protégé.
• Codes de statut attendus : liste ou plage. Par défaut 200-399, mais vous pouvez resserrer à un seul code (par ex. exactement 201 pour un endpoint de création) ou autoriser certains (par ex. 200,202,204).

La vérification suit jusqu’à max. 5 redirections, décode le gzip, analyse le Content-Type pour détecter le JSON. Chaque vérification enregistre le code réel, le temps de réponse, la taille et toute erreur éventuelle. Plusieurs échecs consécutifs (configurable, par défaut 2) déclenchent un incident.

Assertions JSON path

Les seuls codes de statut ne suffisent pas pour de nombreuses API. Un endpoint health peut renvoyer 200 avec un body {"status": "degraded", "db": "down"} – toujours un 200, mais il faut absolument le savoir. Une API de prix peut renvoyer 200 avec un body où data.price est devenu null. Une API de recherche peut retourner 200 avec results: [] parce que l’index est tombé.

Pour ces cas, configurez une assertion JSON path. Définissez le chemin (par ex. data.status ou health.checks.db) et la valeur attendue (par ex. healthy, true ou un nombre précis). À chaque vérification, la réponse est décodée depuis le JSON et la valeur sous le chemin est comparée. Une non-correspondance termine le check par un échec, quel que soit le statut HTTP.

La syntaxe du chemin utilise la notation pointée avec crochets : data.items[0].id fonctionne, tout comme users.john.email. La valeur à vérifier est comparée en tant que chaîne, donc "true" correspond au booléen true, et les nombres correspondent aussi bien sous forme de chaîne que de nombre.

Modèles d’authentification

Les deux styles d’authentification les plus courants fonctionnent nativement. Pour les tokens Bearer (OAuth, JWT, clés API) utilisez le champ headers : {"Authorization": "Bearer eyJhbGciOi..."}. Le token est présent dans la configuration du moniteur et envoyé à chaque vérification. Pour le basic auth, utilisez les champs dédiés utilisateur/mot de passe – ils sont stockés et combinés dans un header standard.

Si l’authentification exige une signature spécifique à chaque requête ou un rafraîchissement du token, cela se complique. Deux modèles raisonnables : (1) configurez un token long terme dédié au monitoring pour un compte de service, ou (2) exposez un endpoint health non authentifié qui reflète le statut du vrai endpoint protégé, et monitorez-le. La plupart des API modernes proposent déjà cela nativement.

Bonnes pratiques recommandées

• Un monitor par endpoint critique. Ne testez pas tout – choisissez 5 à 10 endpoints dont la défaillance aurait un impact réel.
• Utilisez des codes exacts. Le 200-399 par défaut est trop permissif pour les APIs. Un endpoint de création doit renvoyer uniquement 201 ; un idempotent exactement 200 ; un endpoint login exactement 200 (succès) ou 401 (échec bien formé – pas 500).
• Combinez le code de statut à une assertion JSON. Ensemble, ils détectent les régressions de la couche transport et contenu. Le code de statut seul ne détecte pas les erreurs de contenu ; l’assertion JSON seule est fragile en cas de redirection.
• Placez un seuil sur le temps de réponse. La dégradation de l’API est un indicateur précoce de problèmes de dépendances. Un monitor avec rt_threshold_ms = 800 vous avertit que l’API ralentie avant qu’elle ne tombe totalement.
• Gardez le body petit. Les checks se font chaque minute – un body volumineux gaspille la bande passante des deux côtés. Un payload représentatif mais minimal suffit.

Combinez avec d’autres types de moniteurs

Pour chaque endpoint API, un monitor API vérifie que l’appel fonctionne. Un moniteur ping ou port distinct vérifie que l’hôte est vivant. Un check SSL/domaine sur le même hostname détecte les problèmes de certificat et d’enregistrement. Un sous-moniteur DNS surveille les changements de records qui pourraient indiquer un détournement. Ensemble, quatre moniteurs sur une API vous donnent une vue complète avec un minimum de recoupement.

Configuration

Ouvrez l’outil, cliquez sur “Ajouter un monitor”, choisissez le type “API”. Collez l’URL. Ouvrez la section Avancé. Sélectionnez la méthode, collez les headers comme du JSON, collez le body si besoin, paramétrez le basic auth si vous l’utilisez, indiquez les codes attendus (par ex. 200 ou 200,201). Ajoutez une assertion JSON path si nécessaire. Définissez l’intervalle et le seuil de confirmation. Enregistrez. Dès le prochain cycle, le monitor interroge votre API exactement comme le ferait un intégrateur, valide la réponse et alerte à la moindre régression.

Questions fréquemment posées

• Quelles méthodes HTTP puis-je utiliser pour le monitoring API ?

  GET, POST, PUT, DELETE, PATCH et HEAD. Configurez la méthode par monitor — pour les endpoints d’écriture (POST/PUT/PATCH), le body de la requête est aussi configurable en chaîne JSON ou données de formulaire.

• Comment fonctionnent les assertions JSON ?

  Vous indiquez un chemin JSON (par ex. data.status ou results[0].id) et la valeur attendue. Le monitor récupère la réponse, la parse en JSON, extrait le chemin et le compare à la valeur attendue. En cas de différence, le check échoue avec une erreur "assertion failed" affichant la valeur réelle.

• Puis-je envoyer des headers d’authentification ?

  Oui. Les headers HTTP personnalisés sont configurables par monitor — tokens Authorization, clés API, content-type, etc. Les valeurs des headers sont chiffrées au repos dans la base. Pour le Basic Auth, il y a un champ dédié username/password qui signe automatiquement la requête.

• Que faire si mon API retourne 200 avec un payload d’erreur ?

  Cas courant : l’API renvoie HTTP 200 mais le body affiche {"status":"error"}. Un simple monitor uptime croira que tout va bien. Utilisez une assertion JSON status == "ok" pour détecter cela — l’assertion échoue et le monitor signale DOWN même si HTTP indique 200.

• Comment surveiller une API avec un rate limit ?

  Réglez l’intervalle des checks pour respecter la limite de l’API (par ex. intervalle de 5 minutes si l’API autorise 12 appels/heure). Un monitor compte pour un appel API par check depuis une région. Les checks multi-régions multiplient le nombre d’appels – privilégiez le single-region si votre API a des limites strictes.