Comment éviter les changements d'API cassants avec API Gateway

Lorsque vous développez des API, vous modifiez parfois des éléments qui pourraient causer des problèmes pour les consommateurs actuels de l'API. Faire évoluer votre API sans affecter les utilisateurs actuels est essentiel, sinon, ils pourraient perdre confiance en votre offre. Il est impossible d'éviter complètement ces problèmes, mais vous pouvez minimiser leur impact ou détecter certains changements critiques avant qu'ils ne se produisent. Les changements critiques doivent être identifiés pendant la phase de développement, et s'ils se produisent, la passerelle API doit les gérer pour garantir que les applications clientes restent inchangées. Dans cet article, nous explorerons quelques bonnes pratiques et stratégies pour prévenir les changements critiques dans les API et comment les gérer en utilisant la passerelle API APISIX.

Qu'est-ce qu'un changement critique dans une API ?

Les produits logiciels évoluent constamment, et leurs API ne font pas exception. Ces API servent d'interface principale à travers laquelle les consommateurs externes interagissent avec votre système, reflétant ainsi tout changement du produit. Il existe diverses raisons pour ces modifications d'API, notamment l'amélioration technologique, les changements de direction commerciale, la résolution de bugs critiques, et plus encore. En termes simples, un changement critique se produit lorsque vous modifiez votre API et que cela pourrait causer des problèmes pour les applications clientes qui l'utilisent. Certains de ces changements sont plus faciles à repérer que d'autres. Voici quelques exemples de changements critiques :

1. Suppression d'un point de terminaison : Si vous avez un point de terminaison GET /users et que vous décidez de le supprimer, tout client essayant d'y accéder recevra des erreurs.
2. Changement de l'URL d'un point de terminaison : Si vous changez l'URL d'un point de terminaison de GET /users à GET /members, tout client utilisant l'ancienne URL rencontrera des problèmes.
3. Modification du corps de la requête : Si un point de terminaison attend des données spécifiques dans la requête, comme POST /users attendant { "name": "John" }, mais que vous changez l'exigence en { "firstName": "John" }, cela perturbera les clients envoyant l'ancien format.
4. Suppression ou renommage de champs dans la réponse : Si les clients s'attendent à des champs spécifiques dans la réponse de l'API, leur suppression ou renommage entraînera un dysfonctionnement de ces clients. Par exemple, changer { "id": 1, "name": "John" } en { "id": 1, "fullName": "John Doe" }.
5. Changement de types de données : Si un champ de l'API est censé être une chaîne de caractères et que vous le changez en un entier ou un autre type, cela peut casser les clients. Par exemple, changer "age": "25" en "age": 25.
6. Changement des mécanismes d'authentification : Si vous passez de l'authentification de base à l'authentification par jeton sans transition appropriée, les clients existants rencontreront des erreurs d'authentification.
7. Introduction de champs obligatoires : Si vous avez un point de terminaison comme POST /users qui prend des champs optionnels, et que vous rendez soudainement l'un de ces champs obligatoire, les clients existants ne l'envoyant pas rencontreront des problèmes.
8. Changement des formats d'erreur : Si les clients sont programmés pour comprendre des formats d'erreur spécifiques, changer ces formats peut entraîner une gestion incorrecte des erreurs côté client.
9. Modification des codes de statut HTTP : Changer les codes de statut pour certaines opérations, comme retourner un 200 OK au lieu d'un 201 Created pour la création de ressource, peut induire en erreur les clients.
10. Dépréciation du support des anciennes versions de l'API : Si vous supprimez le support des anciennes versions sans une période de transition appropriée, les clients dépendant de ces anciennes versions cesseront de fonctionner.

Chaque changement dans une API a le potentiel de casser une application cliente. Si vous utilisez une passerelle API comme une porte d'entrée pour toutes les API backend, la passerelle sait où rediriger la requête en fonction d'un ensemble de règles définies dans une configuration de route, et c'est l'endroit idéal pour gérer les changements critiques dans les API. Voyons comment nous pouvons utiliser APISIX pour identifier certains changements d'API.

Validation des schémas de requête et de réponse

Définir des schémas stricts pour vos routes vous permet de vous assurer que les structures de requête et de réponse sont conformes aux attentes. Utilisez le plugin request-validation pour valider les requêtes entrantes et le plugin response-rewrite pour réécrire la réponse de l'API en fonction de certaines conditions.

Journalisation

APISIX prend en charge divers plugins de journalisation, tels que http-logger, elasticsearch-logger, file-logger, et plus encore. Configurez un journal pour stocker les données de requête et de réponse de l'API et analysez régulièrement les journaux pour détecter des changements dans les en-têtes de requête/réponse, les structures de charge utile, ou tout autre motif inhabituel.

Surveillance des routes et des services en amont

Surveillez les routes passant par la passerelle. Si une route précédemment disponible commence soudainement à retourner des erreurs 404, c'est un signe potentiel que l'API a subi un changement ou qu'un point de terminaison a été déprécié. Activez la fonctionnalité de contrôle de santé de l'API pour surveiller en continu l'état de santé global des nœuds en amont. Si l'un des nœuds commence à échouer, répondant plus rapidement ou plus lentement que d'habitude, cela pourrait indiquer un changement dans le traitement du service backend sous-jacent. Intégrez APISIX avec des outils de surveillance comme Prometheus en utilisant le plugin prometheus. Configurez des alertes basées sur des métriques, comme une augmentation du taux d'erreurs 4xx ou 5xx, ce qui pourrait indiquer des changements critiques dans votre API.

Utilisation du versioning

Le versioning des API est la pratique de gérer les changements dans une API et de s'assurer que ces changements sont effectués sans perturber les applications consommatrices de l'API. Il existe diverses méthodes pour configurer le versioning avec APISIX, comme l'utilisation de chemins d'URI, de paramètres de requête, d'en-têtes, ou la sélection du type de contenu. Par exemple, vous pourriez avoir des adresses web comme /v1/users ou /v2/users pour montrer la version de votre API. En ayant ces versions, vous pouvez offrir plus d'une option de votre API, permettant aux consommateurs de l'API de décider quand passer à la dernière version à leur propre rythme. APISIX peut facilement rediriger tout le trafic vers l'ancienne version stable de l'API jusqu'à ce que vous résolviez les problèmes dans la nouvelle version, rendant vos API rétrocompatibles. Utilisez APISIX pour maintenir l'ancienne compatibilité tout en déployant les nouveaux changements. Si vous détectez des problèmes dans la nouvelle version, le plugin traffic-split permet un retour en arrière rapide.

Avis de dépréciation

Avant de supprimer ou de modifier des fonctionnalités, marquez-les comme dépréciées, donnant ainsi aux consommateurs un temps suffisant pour s'adapter. Avec l'aide d'APISIX, nous pouvons configurer la route pour communiquer sur sa future dépréciation et son remplacement. Pour cela, APISIX offre le plugin response-rewrite.

Intégration avec le contrôle de version

Bien que vous souhaitiez que les relecteurs de demandes de pull repèrent tout changement critique, compter uniquement sur cette méthode n'est pas certain et pourrait éventuellement conduire à un échec. Si vous avez une documentation OpenAPI/Swagger pour vos API, celles-ci peuvent être versionnées et incluses dans un pipeline CI. APISIX ne prend pas en charge nativement l'intégration directe avec des systèmes de contrôle de version comme Git pour les changements de spécification d'API. Cependant, vous pouvez configurer un processus en dehors d'APISIX. Des outils comme Oasdiff ou Bump peuvent identifier les changements dans les spécifications d'API et déclencher un pipeline CI (ajoutez GitHub Action) qui exécute des tests sur les points de terminaison de route dans APISIX pour s'assurer qu'aucun changement critique n'est introduit.

Autres moyens de détecter les changements

Postman contient un modèle pour vérifier automatiquement la version actuelle de votre API pour des changements critiques et décrit comment cela fonctionne dans cet article. Vous ajoutez le détecteur au pipeline CI comme une étape supplémentaire. Chaque fois que votre pipeline s'exécute, le détecteur de changements critiques analysera la spécification actuelle de l'API par rapport à la précédente et vous informera de toute différence. Selon votre pile de développement, il existe d'autres bibliothèques pour comparer les spécifications OpenAPI. Cet article explique bien comment les détecter en pratique en utilisant des stratégies de déploiement testées avant de mettre en production les nouveaux changements.

Résumé

Détecter et prévenir les changements critiques dans les API est important pour maintenir la confiance des consommateurs d'API et assurer le succès de votre service. En intégrant les capacités d'APISIX comme la validation des requêtes, le versioning, la journalisation, la surveillance et l'alerte avec des techniques comme les tests automatisés de contrat d'API, vous pouvez vous assurer que vos API évoluent sans affecter négativement vos clients.

Ressources connexes

Maintenir la santé des API avec APISIX et Prometheus

Validation des requêtes dans la passerelle API