Faut-il généralement développer une bibliothèque cliente pour les services REST pour aider à prévenir les ruptures d'API?

Nous avons un projet où le code UI sera développé par la même équipe mais dans un langage différent (Python / Django) de la couche services (REST / Java). Le code de chaque couche se termine dans différents référentiels de code et qui peuvent suivre différents cycles de publication. J'essaie de trouver un processus qui empêchera / réduira les changements de rupture dans la couche services du point de vue de la couche d'interface utilisateur.

J'ai pensé à écrire des tests d'intégration au niveau de la couche d'interface utilisateur que nous exécuterons chaque fois que nous construisons l'interface utilisateur ou la couche de services (nous utilisons Jenkins comme notre outil CI pour construire le code qui est dans deux dépôts Git) et si il y a des échecs, puis quelque chose dans la couche services s'est cassé et la validation n'est pas acceptée.

Serait-ce également une bonne idée (est-ce une meilleure pratique?) Que le développeur de la couche de services crée et gère une bibliothèque cliente pour le service REST qui existe dans la couche d'interface utilisateur qu'il mettra à jour chaque fois qu'il y aura un changement de rupture leur API de service? En théorie, nous aurions alors l'avantage d'une API de type statique sur laquelle le code de l'interface utilisateur s'appuie. Si l'API de la bibliothèque client change, le code de l'interface utilisateur ne se compilera pas (nous saurons donc plus tôt qu'il y a eu un changement de rupture). J'exécuterais également les tests d'intégration lors de la création de l'interface utilisateur ou de la couche services pour valider davantage que l'intégration entre l'interface utilisateur et le (s) service (s) fonctionne toujours.

En général, pour les méthodes de l'API qui disparaissent, choisissez une convention et «dépréciez», en particulier dès qu'une API complète et de remplacement est disponible et testée. Laissez l'ancienne API en place (essentiellement), mais balisez les métadonnées de signature de méthode ou insérez un événement de journalisation afin que l'utilisation puisse être clairement identifiée.

La journalisation dans l'API de service est une chose, mais alerter les clients consommateurs en est une autre. Pour REST, je ne pense pas qu'il existe une pratique solide et standard. Les clients de l'API FourSquare peuvent découvrir des méthodes obsolètes même si la méthode appelée réussit (code HTTP 200, cependant errorType sera défini sur «obsolète»). Peut-être une stratégie raisonnable pour fournir aux clients consommateurs la possibilité de connaître une méthode obsolète dans l'API sans provoquer de rupture.

https://developer.foursquare.com/overview/responses

Dans votre guide API, proposez une date ou un numéro de version de build où l'API obsolète sera complètement supprimée. Au fur et à mesure que vous étoffez votre stratégie de dépréciation, vous souhaiterez alerter les consommateurs de l'API sur la stratégie proposée (comment peuvent-ils découvrir les méthodes déconseillées, comment passer à l'API de remplacement et quand l'API dépréciée ne sera plus disponible si purgée lors du nettoyage de l'API), et sollicitez leurs commentaires pour vous assurer que le processus est bénéfique pour tout le monde.

La version de votre API est une autre possibilité. Lorsqu'une nouvelle version est déployée, laissez également l'ancienne version active et autorisez la négociation via la demande. Si vous conservez les versions 2 ou 3 les plus récentes, le code de l'interface utilisateur peut être mis à niveau à son rythme.

Il y a au moins trois questions à la fois, faisons-les une par une

• "est-ce une bonne idée d'avoir une bibliothèque cliente pour le service REST?"

Très probablement oui, tant que vous ne voulez pas que les appels REST arbitraires soient dispersés directement dans tout votre code d'interface utilisateur.

• "est-ce une bonne idée de laisser le développeur de la couche services créer et maintenir la bibliothèque?"

Cela dépend des personnes de votre équipe. Le responsable de l'API doit connaître à la fois les éléments disponibles dans la couche services ainsi que les exigences de la couche interface utilisateur. Il peut donc s'agir soit d'une personne de la couche services, soit d'une personne de la couche interface utilisateur, ou (selon la taille et d'autres tâches) d'une personne indépendamment des deux équipes.

• [tirerons-nous un avantage du fait que] "si l'API de la bibliothèque client change, le code de l'interface utilisateur ne se compilera pas"

N'avez-vous pas dit que l'interface utilisateur sera écrite en Python? Ce n'est pas un langage de type statique, donc je ne m'attendrais pas à une rupture de build immédiate suite à un changement d'API. Je suppose que je me suis trompé à ce stade et que vous avez une API de type statique ici - alors vous pouvez obtenir des avantages ici tant que la construction ne se casse pas en ajoutant simplement de nouvelles fonctionnalités (comme de nouveaux paramètres facultatifs) à l'API. Sinon, vous produirez beaucoup de frais généraux inutiles à votre équipe.