Tester une API et la mettre en service

Tester une API et la mettre en service

1. Tester une API : ce que les tests doivent couvrir

   Une API se teste plus facilement qu'une interface, parce que son comportement est entièrement décrit par ses entrées et ses sorties. Cela ne dispense pas de tester les cas que personne n'écrit.

   La pyramide appliquée à une API

   1. unitaire : la validation d'entrée, la logique métier, la construction de la réponse. Millisecondes, aucun serveur ;
   2. d'intégration : une vraie base, un vrai serveur d'application, la pile complète. C'est ici que naissent les défauts d'authentification et de sérialisation ;
   3. de contrat : la spécification exécutée comme un test. Un test de contrat échoue si l'implémentation s'écarte de la spécification, dans les deux sens — une route documentée mais absente compte autant qu'une route non documentée. C'est le seul moyen d'empêcher la spécification de périmer, et c'est la réponse au reproche classique « la documentation est fausse » ;
   4. de bout en bout : les parcours critiques, en nombre très réduit.

   Les cas que tout le monde oublie

   • l'objet d'un autre utilisateur : le test le plus important d'une API, et le plus rarement écrit. Il doit exister et échouer si la vérification d'accès a été retirée ;
   • les entrées hostiles : champ attendu mais absent, type inattendu, valeur aux limites, chaîne très longue, caractère non attendus ;
   • les trois états de toute dépendance : réponse lente, réponse en erreur, dépendance indisponible. Une API qui n'est testée que dans le cas nominal n'est pas testée ;
   • la répétition : la même requête rejouée, en particulier sur une création, doit produire le comportement documenté.

2. Mise en service, observation et versionnement

   Une API publiée est un contrat qui vit : il faut la surveiller, la faire évoluer et savoir ce qu'elle fait réellement.

   Ce qu'il faut observer

   • le taux d'erreur par code de statut, par route et par version. Une hausse de 401 sur une seule route signale un problème de jeton, pas une panne générale ;
   • la latence au 95ᵉ et au 99ᵉ centile. La moyenne est inutile : une moyenne correcte avec un 99ᵉ centile à trente secondes donne l'impression que tout va bien jusqu'à la première plainte ;
   • le débit par client : il révèle les clients dont l'usage a changé, souvent avant tout le reste ;
   • le nombre de requêtes en erreur par cause, pas seulement en nombre. C'est le chiffre qui permet d'agir, contrairement au total.

   Faire évoluer sans casser

   Trois règles, dans cet ordre :

   1. ne jamais supprimer ni changer la forme d'un champ existant. Ajouter est correct ; changer le sens d'un champ ne l'est pas, même si le nom reste le même — c'est la pire rupture possible, parce qu'elle est silencieuse ;
   2. versionner dans l'URL lorsque le changement est incompatible. Le numéro de version dans l'URL est moins élégant que dans un en-tête, et c'est le seul qui fonctionne partout, y compris dans un journal de serveur ou une URL de navigateur ;
   3. prévoir le retrait. Une version dépréciée doit avoir une date de fin communiquée. Une version annoncée « temporaire » sans date est définitive, et le client le découvre à la mauvaise heure.

   La documentation, conditionnée par l'usage

   Une documentation d'API publiée est un service : elle évolue, elle a des versions, et elle a des lecteurs pressés. Les trois erreurs habituelles sont de la documenter une fois à la livraison, d'en écrire trois pages là où une suffit, et d'omettre la section la plus utile de toutes — les exemples complets et exécutables, un par cas d'usage courant. Un exemple qui marche remplace un paragraphe entier.

3. Projet final et évaluation

   Le projet

   Concevoir et implémenter l'API d'un service métier de son choix : spécification OpenAPI rédigée avant l'implémentation, authentification par jeton, contrôle d'accès par objet, pagination, limites de débit, idempotence sur la création, et suite de tests dont un test de contrat exécuté contre la spécification.

   Les huit critères d'évaluation

   1. la spécification précède le code, et le test de contrat s'exécute dans l'intégration continue ;
   2. le contrôle d'accès par objet est testé explicitement, et le test échoue si la vérification est retirée. C'est le critère numéro un ;
   3. les codes de statut distinguent 401 et 403, et aucun 200 ne porte une erreur dans son corps ;
   4. le format d'erreur est unique, avec un code stable et un détail par champ ;
   5. la pagination et les limites existent et renvoient un 429 exploitable quand le débit est dépassé ;
   6. la création est idempotente grâce à une clé fournie par l'appelant, et le comportement est testé par répétition ;
   7. les cas d'erreur sont testés : validation, dépendance indisponible, délai dépassé ;
   8. le découplage des états : la documentation le dit, les en-têtes le permettent, et le client n'a pas à deviner.

   Le critère qui départage

   Le jury retient ceci : l'API reste-t-elle utilisable par quelqu'un qui n'a jamais vu son code ? Test final à faire passer : donner la spécification à un collègue et lui demander de créer une ressource sans poser de question. Les questions qu'il pose sont exactement les zones d'ombre de l'API — et une API qui exige de poser des questions n'est pas terminée.