Documentation

Savoir que votre API répond correctement, pas seulement qu’elle répond

La plupart des pannes d’API échappent à une simple vérification du code de statut. Le framework intercepte l’exception et répond 200 OK avec {"error": "database unavailable"}. Un import raté laisse la liste des produits vide. Un cache continue de servir les données d’avant l’arrêt de la tâche qui l’alimente. Dans chacun de ces cas, l’API est « disponible » — et en panne pour tous les clients qui l’appellent.

Pingsured lit le JSON de la réponse et vérifie les valeurs qui disent si l’API fonctionne réellement.

Que vérifier ?

Un endpoint de santé qui indique l’état de ses dépendances est le point de départ le plus simple. S’il répond {"status": "ok", "db": "ok", "queue": {"depth": 12}} :

La dernière ligne est celle qu’un code de statut ne vous donnera jamais : l’API répond, et le travail qu’elle doit traiter ne s’accumule pas.

Pour un endpoint qui renvoie des données plutôt qu’un statut, vérifiez la forme des données elles-mêmes :

Une liste vide, un prix à zéro ou une réponse vieille de plus d’un quart d’heure font chacun échouer le ping, alors que le serveur continue de répondre 200.

Endpoints protégés

Ajoutez les en-têtes qu’attend l’API — un jeton Authorization: Bearer, un en-tête de clé d’API — ou une authentification HTTP basique. Donnez à la vérification son propre jeton, en lecture seule : il est enregistré avec le ping, et un jeton créé pour la surveillance peut être révoqué sans rien casser d’autre.

Pourquoi surveiller votre API avec Pingsured

• Des comparaisons typées. Le nombre 12 n’est pas égal à la chaîne "12" : un changement de sérialisation qui transforme des nombres en chaînes — et casse tous les clients strictement typés — fait échouer la vérification au lieu de passer inaperçu.
• La fraîcheur sans script. Les opérateurs d’âge lisent les horodatages ISO 8601, les dates HTTP et le temps Unix : « les données ont moins d’une heure » tient en une ligne, et non dans une tâche cron qu’il faudrait surveiller à son tour.
• Jusqu’à 16 vérifications JSON par ping, librement combinées avec le code de statut, une vérification d’en-tête et une recherche de texte. Le ping ne réussit que si toutes réussissent.
• Vérifiée depuis les régions de vos clients. Chaque emplacement est évalué séparément : une API qui échoue derrière un nœud de CDN ou depuis une région n’est pas masquée par les autres.
• Des alertes là où vous travaillez. Par e-mail et dans l’application par défaut ; à partir de l’offre Team, par webhook vers votre outil de gestion d’incidents ou votre messagerie.
• Les détails de votre API restent dans l’UE. Endpoints, en-têtes et jetons font partie de ce qu’enregistre un compte de surveillance. Pingsured les stocke en Allemagne et en Finlande, sans passer par aucun service américain.

Limites à connaître

• Les vérifications envoient des requêtes GET ou HEAD. Une API joignable uniquement en POST — la plupart des installations GraphQL, SOAP — ne peut pas encore être vérifiée.
• Chaque vérification est une seule requête. Un scénario qui s’authentifie d’abord puis appelle l’API avec la session obtenue n’est pas possible ; un jeton longue durée dans un en-tête, si.
• Le corps de la réponse est lu jusqu’à 1 Mo, et un JSON coupé à cette limite n’est plus analysable. Pointez la vérification vers un petit endpoint ou une page d’une liste, pas vers un export complet.