Imaginons une équipe qui développe un portail client. L’architecte propose de définir d’abord les contrats API pour que les développeurs web, mobiles et les partenaires puissent avancer indépendamment. Mais si le projet ne comporte au départ qu’une application, une équipe et une base de données ? Concevoir les interfaces tôt peut rester utile ; créer un service réseau distinct est une autre décision.
L’approche API-first consiste à concevoir les interfaces en amont et à maintenir leurs engagements comme une composante du produit. Elle peut faciliter la coordination, mais exige des choix sur la compatibilité, les droits, les erreurs et la responsabilité du contrat. La question est de savoir qui a besoin de cette interface fiable.
Le contrat précède l’implémentation
L’équipe définit les ressources, opérations, données échangées, règles d’accès et comportements en cas d’erreur. OpenAPI fournit une description standard des API HTTP, indépendante du langage, utilisable par la documentation et les outils. Cette description ne prouve pas que l’implémentation la respecte : des contrôles et un responsable restent nécessaires.
Le contrat évolue avec les connaissances du projet. Dès que d’autres applications en dépendent, ses modifications doivent être examinées, annoncées et testées. Les tests de contrat détectent certaines incompatibilités ; ils ne remplacent ni les tests de bout en bout ni les contrôles de sécurité.
Quand plusieurs équipes partagent les mêmes fonctions
Dans ce scénario fictif, ajoutons une application mobile et des partenaires utilisant les mêmes données clients et commandes. Ils ne peuvent pas nécessairement se mettre à jour chaque fois que le backend renomme un champ. Un contrat stable peut réduire la coordination imposée à chaque livraison.
Concevoir l’interface en premier permet de discuter des données, permissions et erreurs avant que des hypothèses divergentes se répandent entre les clients. Cette autonomie suppose cependant un contrat entretenu. Qui maintient la documentation, examine les changements incompatibles et décide de la durée de prise en charge des anciennes versions ? Sans responsable, la spécification reste un document supplémentaire.
API-first n’impose pas un service séparé
API-first décrit une démarche de conception, pas une architecture de déploiement. Un monolithe peut suivre cette démarche et exposer des endpoints HTTP dans la même application. Ni les microservices, ni une base de données distincte, ni un frontend headless ne sont obligatoires.
Changeons maintenant une condition : le portail reste une application unique, rendue côté serveur et gérée par une seule équipe, sans consommateurs autonomes. Des modules internes bien conçus peuvent suffire. Cette comparaison porte sur la nécessité d’une frontière réseau, pas sur l’intérêt d’interfaces explicites.
Une frontière réseau introduit délais d’attente, pannes partielles, contrôles d’accès et supervision. Un déploiement séparé ajoute ses propres responsabilités. WordPress montre que rendu des pages et API REST peuvent coexister : exposer le contenu n’oblige pas à remplacer tout le frontend.
Concevoir aussi la requête sans réponse
Les réponses réussies ne couvrent qu’une partie du contrat. Que se passe-t-il si un jeton expire, qu’un enregistrement manque ou qu’un fournisseur ne répond plus ? Il faut décider si l’utilisateur doit réessayer et quelles requêtes le client peut répéter sans danger.
Un timeout ne prouve pas que l’opération initiale a échoué. Répéter aveuglément une demande de paiement ou de création de ticket peut produire des doublons. Définissez les erreurs, règles de nouvelle tentative et mécanismes d’idempotence nécessaires. Stripe documente les clés d’idempotence comme exemple concret ; leur comportement et leur durée de conservation restent propres au fournisseur.
Le contrat décrit ainsi le comportement attendu, au-delà des champs JSON. Développeurs et exploitants ont besoin de ces engagements pendant un incident.
Les versions engagent envers les consommateurs
GitHub utilise des versions datées de son API REST et documente les changements incompatibles : suppression de champs, paramètres devenus obligatoires ou modification des conditions d’accès. Les consommateurs disposent ainsi d’un cadre explicite de migration.
Ce modèle n’est pas universel. Chaque équipe doit définir une politique adaptée à ses consommateurs. Les ajouts sont souvent moins perturbants que la modification d’un comportement existant, mais leur effet dépend aussi de la manière dont les clients interprètent le contrat.
Quels éléments justifient l’investissement ?
Partez des dépendances réelles : consommateurs autonomes, responsable du contrat, contrôles des changements et gestion des incidents. Comparez la frontière réseau proposée à un module interne et consignez les conditions qui justifieraient de revoir ce choix.
| Question | Élément à établir |
|---|---|
| Existe-t-il des consommateurs autonomes ? | Le contrat partagé réduit la coordination des livraisons. |
| Comment gérer les changements incompatibles ? | Un responsable, une politique de compatibilité et une migration vérifiable existent. |
| Les erreurs sont-elles définies ? | Timeouts, accès refusés, nouvelles tentatives et doublons ont un comportement attendu. |
| L’équipe peut-elle exploiter l’API ? | Sécurité, supervision, documentation et responsabilité des incidents sont organisées. |
| Un module interne suffirait-il ? | L’interface réseau apporte une valeur identifiable face à cette solution. |
La même rigueur peut s’appliquer aux interfaces d’une petite application sans transformer chaque module en service. Voir aussi le dossier d’architecture web.
Une bonne API ne se mesure pas au nombre d’endpoints
API-first est utile lorsque des contrats explicites permettent aux consommateurs de travailler de façon prévisible. Les frontières réseau inutiles et les contrats sans responsable créent des coûts ; la démarche ne les impose pas. Formalisez les engagements indispensables et retenez le déploiement le plus simple qui les respecte.
Sources
- OpenAPI Specification v3.2.1
- GitHub API Versions
- GitHub Breaking Changes
- WordPress REST API Handbook
- Stripe — Idempotent requests
Contactez-nous
Dites-nous comment nous pouvons vous aider ; nous répondons sous deux jours ouvrés.
