Faire d'un contrat d'API la source unique de vérité
Faire d'un contrat d'API la source unique de vérité, et en dériver automatiquement clients, types et validations plutôt que de les recopier à la main, est une pratique que j'applique dès qu'un projet comporte une API bien définie.
Le besoin type
Sur un projet avec une API consommée par plusieurs consommateurs — un frontend, une application mobile, un partenaire externe — la description du contrat d'échange se retrouve souvent recopiée à plusieurs endroits : dans le code backend, dans le code frontend, dans une documentation à part. Ces copies divergent presque inévitablement dans le temps, un champ renommé côté backend sans que le frontend ne soit mis à jour en même temps, une documentation qui devient fausse sans que personne ne s'en aperçoive.
Comment j'interviens sur ce genre de besoin
La spécification OpenAPI décrit précisément les routes, les paramètres, les formats de requête et de réponse d'une API, dans un format structuré et lisible par des outils. Plutôt que de l'écrire après coup à titre documentaire, je la traite comme la source de vérité du projet : le code backend peut être généré ou validé à partir d'elle, et surtout le code client (types, fonctions d'appel, validations) est généré automatiquement pour chaque consommateur, sans recopie manuelle.
Cette approche déplace une catégorie d'erreurs du moment de l'exécution en production vers le moment de la compilation ou de la génération : un champ renommé dans la spécification casse immédiatement la génération du code client, avec une erreur explicite et localisée, plutôt qu'un bug découvert par un utilisateur des semaines plus tard. La mise en place initiale demande une discipline de mise à jour de la spécification à chaque changement d'API, ce qui est un changement d'habitude plus qu'une difficulté technique.
Facteurs qui influencent le chiffrage
-
API existante ou à concevoir
Documenter une API déjà en place demande un travail de reconstitution différent de la conception d'une spécification dès la création de l'API.
-
Nombre de consommateurs de l'API
Le bénéfice de la génération automatique croît avec le nombre de clients différents à maintenir synchronisés avec le contrat.
-
Complexité des types de données
Des structures de données imbriquées ou avec de nombreux cas de validation demandent une spécification plus détaillée à écrire et à maintenir.
-
Intégration à la chaîne de développement
Automatiser la génération à chaque changement de spécification, plutôt qu'une génération manuelle occasionnelle, demande une mise en place initiale supplémentaire dans l'outillage du projet.
Questions fréquentes
Cette approche s'applique-t-elle à une API déjà en production ?
Faut-il changer de langage ou de framework pour adopter cette pratique ?
Que se passe-t-il si la spécification n'est pas tenue à jour ?
Décrivez votre besoin en 1 minute
Quelques questions ciblées pour que je vous réponde avec une estimation, pas avec un questionnaire de plus.