Historique : Dans les architectures monolithiques, les changements d'API étaient gérables grâce aux phases de tests d'intégration. Cependant, avec l'adoption des microservices, l'explosion des dépendances des services a créé un "enfer de versionnage" où un seul changement brisé pouvait entraîner des pannes dans des dizaines de consommateurs en aval. Cela a nécessité un passage de revues manuelles d'OpenAPI à des portes de validation automatisées basées sur des contrats à l'intérieur des pipelines CI/CD.
Le problème : Les tests traditionnels valident qu'une API fonctionne de manière isolée, mais ne détectent pas si les modifications des schémas de demande/réponse violent les contrats implicites avec les consommateurs existants. Les revues manuelles de spécifications sont sujettes aux erreurs et ne peuvent pas s'échelonner sur des centaines de services interdépendants, entraînant des incidents en production où des champs obsolètes sont supprimés alors qu'ils sont toujours en cours d'utilisation.
La solution : Mettre en œuvre un pipeline de validation multi-couches intégrant l'analyse des différences d'OpenAPI avec les tests de contrat dirigés par les consommateurs. Utiliser des outils comme Optic ou Swagger Diff pour catégoriser les changements en tant que rupture (suppression de champ, changements de type) ou non-rupture (ajouts facultatifs). Intégrer Pact pour vérifier que les modifications du fournisseur respectent les attentes des consommateurs enregistrées. Appliquer une automatisation du versionnage sémantique où le pipeline calcule les augmentations de version nécessaires en fonction de la gravité des changements détectés et bloque les déploiements si l'augmentation est insuffisante.
validate_api_compatibility: stage: test script: - optic diff openapi.yaml --base main --severity breaking - pact-verifier --provider-app-version $CI_COMMIT_SHA --publish-verification-results - python scripts/check_semver.py --schema-diff-report optic-report.json rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"
Notre équipe maintenait une API de passerelle de paiement servant douze microservices internes et trois partenaires bancaires externes. Lors d'une amélioration de routine pour ajouter des champs d'authentification 3D Secure 2.0, un développeur a supprimé le champ de chaîne obsolète transactionReference, le remplaçant par une structure d'objet.
Description du problème : Le changement a passé les tests unitaires et d'intégration car la nouvelle structure gérait les données correctement. Cependant, trois anciens microservices comptables s'attendaient toujours au champ de chaîne plat. La revue manuelle d'OpenAPI a négligé le caractère brisé de ce changement structurel. Lors du déploiement, les tâches de réconciliation ont échoué avec des erreurs de désérialisation, entraînant une panne de quatre heures.
Différentes solutions envisagées :
Revue manuelle par les pairs avec liste de vérification : Exiger que les ingénieurs seniors examinent tous les changements d'OpenAPI en utilisant une liste de vérification des changements critiques. Cette approche repose sur la vigilance humaine mais est fondamentalement peu fiable sous pression, ne s'échelonne pas avec des cycles de déploiement rapides et ne peut pas tenir compte des dépendances cachées des consommateurs.
Comparaison automatisée des schémas JSON : Mettre en œuvre un outil de différence de base qui signale toute différence structurelle comme une erreur. Cela fournit un retour rapide mais produit des faux positifs excessifs en considérant les changements additionnels (nouvelles champs facultatifs) comme des violations, obligeant les équipes à maintenir des listes d'exceptions encombrantes et en fin de compte à ignorer les avertissements en raison de la fatigue d'alerte.
Tests de contrat des consommateurs avec des portes de versionnage sémantique : Déployer Pact pour des contrats dirigés par les consommateurs combinés avec l'Optic CLI pour l'analyse des différences d'OpenAPI. Cela valide les changements par rapport aux interactions réelles des consommateurs enregistrées, garantissant que seules les modifications réellement brisées déclenchent des échecs. Il suggère automatiquement des augmentations de version sémantique et maintient l'application des délais de dépréciation. L'inconvénient est l'investissement initial requis pour embarquer les équipes de consommateurs et le surcoût de stockage pour les artefacts de contrat.
Solution choisie et raisonnement : Nous avons choisi le test de contrat des consommateurs parce qu'il s'alignait avec le besoin de notre architecture de microservices d'avoir des déploiements autonomes tout en prévenant les échecs en cascade. Contrairement aux revues manuelles, cela s'échelonne horizontalement. Contrairement aux outils de comparaison de base, cela comprend l'impact sémantique. Nous avons accepté le coût d'intégration en imposant des tests de contrat uniquement pour les chemins de service critiques dans un premier temps.
Résultat : Les changements brisés ont été éliminés des versions de production au cours des huit mois suivants. La fréquence des déploiements a augmenté d'un rythme bi-hebdomadaire à quotidien car les équipes faisaient confiance aux portes automatisées. Lorsque le même refactoring a été tenté plus tard, la vérification Pact a échoué immédiatement dans la demande de tirage, mettant en évidence l'incompatibilité avec le service hérité.
Comment distinguez-vous les changements brisés syntaxiques et les changements brisés sémantiques dans la validation des API REST ?
Les changements syntaxiques impliquent des modifications structurelles détectables par la comparaison de schéma d'OpenAPI, telles que la suppression de champ ou la modification de type. Les changements sémantiques préservent la structure mais modifient le comportement, comme changer la valeur par défaut d'un paramètre optionnel ou modifier l'ordre de tri des tableaux retournés. La validation pure des schémas passe à côté des ruptures sémantiques, nécessitant des tests comportementaux par le biais de tests de contrat ou de comparaisons de trafic dit ombre pour détecter les sorties modifiées de la logique métier.
Qu'est-ce que le motif d'expansion-contrat, et comment l'automatisation devrait-elle l'appliquer ?
Le motif d'expansion-contrat nécessite d'ajouter de nouvelles fonctionnalités en parallèle avec les anciennes (expansion), de migrer les consommateurs, puis de supprimer l'ancien code (contrat). L'automatisation doit suivre les métadonnées de dépréciation des champs avec des dates de fin, échouant les builds si les champs dépréciés sont supprimés prématurément. De plus, le système doit surveiller la télémétrie pour vérifier qu'il n'y a aucun trafic sur les points de terminaison dépréciés avant de permettre la suppression, assurant une véritable préparation des consommateurs plutôt qu'une simple compatibilité au niveau du code.
Comment validez-vous la compatibilité API lorsque les consommateurs sont des tiers externes qui ne peuvent pas participer à votre pipeline de test de contrat ?
Pour les consommateurs externes où les contrats bilatéraux Pact sont impossibles, mettre en œuvre une simulation de consommateurs synthétiques utilisant le trafic ombre et les tests VCR. Enregistrer les modèles de production pour créer des simulacres représentatifs, puis les rejouer contre de nouvelles versions d'API. Combiner cela avec des déploiements canari présentant des déclencheurs de retour en arrière automatiques, et maintenir des politiques strictes de LTS pour les APIs publiques avec des avis de dépréciation obligatoires s'étalant sur plusieurs trimestres.