Ressources · 33
Faire évoluer les contrats API sans perdre les clients
Décrire requêtes, réponses et erreurs, tester les versions et rendre les webhooks rejouables.
· 20 min
Ce que ce guide permet
- Écrire le contrat
- Rendre les erreurs claires
- Tester la compatibilité
- Préparer le retrait
Contrôle express
- Quels clients consomment chaque opération ?
- Les réponses d’erreur ont-elles un type stable et un statut cohérent ?
- Un ancien client tolère-t-il le changement ?
- Les retries créent-ils des doublons ?
- Comment annoncer et vérifier un retrait ?
Méthode pas à pas
- 01
Inventorier les consommateurs
Lister opérations, clients, usages, versions et responsables. Distinguer usages observés et supposés avant de modifier un champ.
Livrable : carte des dépendances du contrat.
- 02
Décrire requêtes et réponses
Tenir une description OpenAPI avec schémas, exemples réalistes, réponses de succès et d’échec. Vérifier qu’elle reflète le service exécuté.
Livrable : contrat versionné et tests de conformité.
- 03
Stabiliser les erreurs
Utiliser les statuts HTTP selon leur sens et, lorsque pertinent, un type de problème documenté selon RFC 9457. Ne pas divulguer de secret dans les détails.
Livrable : catalogue d’erreurs testées.
- 04
Qualifier le changement
Examiner champs obligatoires, types, valeurs, comportements, délais et pagination. Tester les anciens clients contre la nouvelle version sur des cas représentatifs.
Livrable : matrice de compatibilité et décision de version.
- 05
Fiabiliser les notifications
Pour les webhooks, prévoir authentification, ordre non garanti, doublons et retries. Rendre le traitement idempotent quand une répétition est possible.
Livrable : scénario de replay et accusé de réception.
- 06
Déployer avec sortie claire
Publier notes de migration, période de coexistence et contacts. Mesurer l’usage ancien, puis retirer une version seulement après vérification des consommateurs concernés.
Livrable : plan de migration et preuves de retrait.
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| Contrat | Opérations décrites et conformes au service | Corriger les divergences |
| Compatibilité | Clients représentatifs testés avant changement | Ajouter les cas oubliés |
| Erreurs | Types documentés sans donnée sensible | Réviser messages et schémas |
| Migration | Usage des versions anciennes avec propriétaire | Accompagner les clients restants |
Erreurs fréquentes
- Croire qu’un numéro de version suffit à préserver la compatibilité
- Documenter seulement les réponses 200
- Envoyer une trace interne ou un secret dans une erreur
- Supposer qu’un webhook arrive une seule fois et dans l’ordre
Questions fréquentes
OpenAPI remplace-t-il un test ?
Non. La description doit être comparée aux réponses réelles et aux besoins des consommateurs.
Faut-il toujours créer une nouvelle version ?
Non. La décision dépend de l’effet sur les clients et du comportement du contrat ; les changements incompatibles exigent un plan explicite.
Pourquoi des erreurs typées ?
Elles donnent aux clients une façon stable de distinguer les problèmes et de choisir une action.
Références officielles
Pour aller plus loin
Analyses associées
