Une petite modification de réponse API peut casser un client. Vérifiez le contrat avec les scénarios des consommateurs avant publication. ÉCRIRE LA PROMESSE Pour les opérations importantes, décrivez méthode, adresse, paramètres, champs obligatoires, types et erreurs. OpenAPI propose un format de description des API HTTP, sans prouver à lui seul la conformité du serveur. Désignez un responsable et intégrez cette description au processus de publication. EXAMINER LES CHANGEMENTS DISCRETS Supprimer un champ se remarque vite. Le renommer, transformer un nombre en chaîne, ajouter une valeur d’énumération ou changer le comportement de null peut n’apparaître que chez le client. Même un champ facultatif supplémentaire peut gêner un parseur strict. Séparez les incompatibilités évidentes des changements qui nécessitent un essai avec certains consommateurs. CRÉER UN PETIT JEU D’EXEMPLES Préparez résultat normal, liste vide, champ facultatif absent, erreur de validation et accès refusé avec des données inoffensives. Ajoutez les devises ou formats de date pris en charge si le contrat les utilise. Passez ces exemples dans les versions clientes maintenues, pas uniquement sur le nouveau serveur. Testez les intégrations de paiement dans l’environnement prévu par le fournisseur, sans débit réel. ORGANISER LA TRANSITION Pour une incompatibilité, convenez d’un versionnement et d’une période de migration. Une date dans une tâche interne n’informe pas un utilisateur d’API. Notez qui a été prévenu, où se trouve la documentation et qui surveille les anciennes requêtes. Les recommandations Microsoft traitent le versionnement comme un sujet de support des consommateurs; adaptez le mécanisme au produit. Prévoyez une adresse stable pour la documentation et un sous-domaine API clair. Le nom facilite la navigation sans remplacer la compatibilité. Conservez les résultats de test avec le dossier de publication pour que la prochaine évolution repose sur des preuves. Image : nouvelle photoillustration générée par IA pour cet article; scène conceptuelle, pas une photographie documentaire. Catalogue de domaines: https://domainevery.com/fr/domains Sources primaires: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design https://spec.openapis.org/oas/latest.html
