Dans une implémentation SOA, un service n’a de sens que s’il est invoqué par plusieurs applications ou blocs applicatifs. Par conséquent, tout changement survenant sur un service impacte l’ensemble des consommateurs de ce service. Non seulement ces changements peuvent coûter chers, en plus, l’autonomie du service est un fondement de la mise en œuvre d’une architecture orientée services. L’autonomie se traduit par le fait que le service peut être modifié, déployé et maintenu indépendamment des consommateurs qui l’invoquent.

La façon la plus répondu pour faire face aux changements des services, c’est le versioning. Cela se traduit par la coexistence de plusieurs versions du même service, chacune est utilisée par un ou plusieurs consommateurs. L’introduction de la coexistence de multiples versions d’un même service permet d’avoir des cycles de vie indépendants entre fournisseurs et consommateurs de services, ce qui minimise les impacts globaux sur l’implémentation SOA.

Néanmoins, gérer les versions de services est loin d’être anodin. Sans une approche bien définie, cela pourrait mettre en péril le succès de l’adoption d’une architecture orientée services.

Même si l’approche de versioning peut paraître simple, il est indispensable de traiter les volets suivants entre fournisseurs et consommateurs de services:
La granularité du versioning: vu du client, la notion de versioning doit porter sur le service comme entité à part entière. On parle alors de versioning fonctionnel. Le versioning technique (c’est-à-dire le versioning unitaire du format du message de la requête, du format du message de la réponse, du type de transport, etc.) est à gérer en interne par le fournisseur de service d’une façon transparente par rapport aux consommateurs.

L’unité de versioning: il est indispensable de distinguer les versions majeures (V1, V2, etc.) des versions mineures (V1.x, V2.y) dans l’implémentation d’un service. Une version mineure porte sur une optimisation de performances, correction de bugs, évolution mineure du contrat de service sous condition de compatibilité ascendante entre versions, etc. alors qu’une version majeure porte sur des modifications/évolutions fonctionnelles ou techniques impactant fortement le contrat de service (avec rupture de la compatibilité ascendante) entre fournisseur et consommateurs du service.

La traçabilité d’une version: il est important de détailler, tracer et partager les changements survenus sur les différentes versions d’un service. Cela permettra aux consommateurs d’étudier les impacts fonctionnels et techniques sur leurs applicatifs et planifier des trajectoires de migration/évolution.

Le cycle de vie d’une version : Le cycle de vie doit être partagé par l’ensemble des acteurs pour que chacun puisse gérer l’évolution des versions de services que l’application qu’il gère invoque. Par exemple, la disparition d’une version de service peut profondément impacter le bon fonctionnement d’une application. En revanche, le fournisseur de service ne peut gérer indéfiniment toutes les versions. Un compromis sur le cycle de vie d’une version de service doit être trouvé entre consommateurs et fournisseur.

La stratégie de déploiement et d’invocation des différentes versions d’un service : Trois principales stratégies de versioning se distinguent:

Stratégie 1 – Le versioning est porté par l’URI d’invocation du service

Cela implique qu’un catalogue de versions d’un même service soit géré par le fournisseur et partagé avec les consommateurs. Chaque version est considérée comme un service différent à part entière.

Illustration

Stratégie 2 – Le versioning est porté par la requête d’invocation du service

Cela implique qu’une unique «URI » soit exposé aux consommateurs. La version requise par le consommateur doit être mentionnée dans la requête.

Tip: La version doit être positionnée dans un quelconque entête technique de telle façon que le fournisseur de service n’aura pas à interpréter le contenu fonctionnel de la requête.

La mise en place d’un composant façade est indispensable pour cette stratégie de versioning. Il assure les 2 principales fonctions suivantes :
► Le routage de la requête vers la version requise par le consommateur
► L’adaptation des formats entrants/sortants par rapport aux formats requis par les différentes versions du service.

Pour assurer la stabilité d’un contrat d’interface, il est important à noter que le service façade doit s’adapter à tous les contrats d’interface définis. Ce qui implique la mise en œuvre d’un macro-service le plus générique possible proposant un contrat d’interface n’exposant aucune notion de versioning aux consommateurs. Ce qui rajoute une complexité supplémentaire aux fournisseurs de services qui sont menés à gérer ce type de service.

Illustration

Stratégie 3 – Le versioning est géré par un composant façade du fournisseur

Cette stratégie est semblable à la stratégie 2 en termes de stabilité de contrat d’interface. Seule différence, le client ne fournit aucune version dans sa requête d’invocation mais plutôt un identifiant qui sera exploité par le composant façade pour invoquer la bonne version du service.

Illustration

Le tableau suivant compare ces 3 stratégies en distinguant la vue « consommateur » de celle du « fournisseur » du service.

Quelle stratégie adopter?

Pour minimiser l’impact sur le consommateur et donner plus de flexibilité au fournisseur dans sa gestion des versions, la combinaison des stratégies 1 et 3 est le choix le plus judicieux:
► Les versions majeures seront gérées selon la stratégie 1
► Les versions mineures seront gérées selon la stratégie 3

Cela permet notamment d’éviter:
► les macro-services complexes et ingérables
► d’impacter les consommateurs à chaque mise en œuvre d’une version mineure.

La traduction architecturale générale est illustrée par le schéma ci-dessous :

Suggestion d'articles :

1. Versioning de services REST
2. Des principes (ou quelques idées…) REST et du Mashup
3. Automatiser ses tests de web services grâce à soapUI

Introduction

Le versioning de service est un thème à part entière dans les architectures orientée service tant il structure l’évolutivité d’un service. Les architectures REST n’échappent pas à la règle. Posant les principes généraux de l’architecture, Roy Fielding n’en a pas pour autant décrit tous les méandres. Il n’appartient donc qu’à nous, développeurs et architectes, de définir ce qu’est le versioning des services REST en respectant ces principes. Ce billet traitera donc la problématique de versioning des services REST.

Quand versionne-t-on ?

Les types de changement

Il existe différents types de changements

• On peut être amené à modifier des règles métiers soit parce qu’elles évoluent, soit parce qu’elles sont « bugfixées ».
• On peut être amené à enrichir la signature du service pour répondre à de nouveaux besoins.

Souvent le premier cas n’a pas d’impact sur la signature du service et nous le laisserons volontairement en dehors du scope de cet article même si quelques problématiques de versioning se posent.

Dans le second cas, les évolutions de signature (c’est-à-dire principalement des paramètres d’appels et de réponse) peuvent être soit compatible avec les versions antérieures soit incompatibles.

Changement compatible

Ce sont les changements qui respectent le principe de compatibilité ascendante. Ces changements n’ont aucun impact sur les clients existants, pour peu qu’ils soient correctement implémentés.

C’est-à-dire qu’il respecte les pratiques suivantes :

• Le client ne doit pas tenir compte de l’ordre des éléments dans une représentation (XML par exemple)
• Le client ne doit pas échouer lorsque des éléments sont rajoutés dans une représentation (XML par exemple)
• Le client ne doit pas échouer lorsque de nouveaux codes retours sont ajoutés
• Le client d’une représentation ne doit pas échouer lorsqu’une nouvelle représentation est ajoutée

Par exemple, pour une ressource Album représentée en XML :

1
2
3

<album>
<title>Dark Side of the Moon</title>
</album>

L’ajout d’un champ ne modifie en rien la structuration précédente du message.

1
2
3
4

<album>
<title>Dark Side of the Moon</title>
<artist>Roger Waters</artist>
</album>

Les clients existants ne doivent pas être impactés.

Les changements incompatibles

Les changements dit incompatibles impactent directement les clients existants. Sur l’exemple précédent, si un ou plusieurs clients utilisent l’élément « artist », le fait de passer d’un artiste par album à une liste d’artistes par album rend cet élément inutilisable par ces clients.

1
2
3
4
5
6
7

<album>
<title>Dark Side of the Moon</title>
<artists>
<artist>Roger Waters</artist>
<artist>David Gilmour </artist>
</artists>
</album>

Un client, même codé selon les règles de l’art du parsing XML, ne pourra pas absorber la modification. (nom, granularité, type, …)

Quand versionner une représentation ?

Les changements compatibles correspondront donc à un changement mineur, les changements incompatibles seront des changements majeurs. Ce sont ces derniers qui obligent une montée de version du service. On changera donc de version lorsque qu’un changement de comportement du service entraîne :

• un changement incompatible
• la création d’un lien vers une nouvelle ressource
• la dépréciation d’une ressource.

Le versioning en REST

Il existe plusieurs moyens de versionner.

Le versioning via URL

La première réponse à ce problème de versioning a été de rajouter un paramètre identifiant la version dans l’URL de la ressource.

Par exemple la version 1 d’une ressource album avec une représentation XML :

1
2
3
4
5
6

GET http://.../v1/albums/12133
 
<album>
	<title>The dark side of the moon</title>
	<artist>The pink floyds</artist>
</album>

Et la version 2 de la même ressource album avec une représentation XML aussi :

1
2
3
4
5
6
7
8
9
10
11

GET http://.../v2/albums/12133
 
<album>
	<title>The dark side of the moon</title>
	<artists>
		<artist>Roger Waters</artist>
		<artist>David Guilmour</artist>
		<artist>Nick Mason</artist>
		<artist>Rick Wright</artist>
</artists>		
</album>

Ce versioning est inspirée du modèle SOAP où la version est portée dans l’adressage du service. A chaque nouvelle version d’un service on définie une nouvelle URL et un nouveau schéma WSDL associé.

Cette approche ne nous satisfait pas sur plusieurs points :

Rupture avec les principes REST :

La plus importante est que cette approche est en rupture avec un des principes de REST : une ressource est identifiée par une URI sous entendu durable et stable dans le temps
L’introduction de la version dans l’URI implique de définir une URI différente par version de la ressource maintenue par le serveur.
Dans l’exemple précédent deux URI permettent d’accéder à la ressource Album.

De plus cette approche donne l’impression aux utilisateurs que l’album dans une version de l’API est une ressource différente du même album dans une autre version. Hors, ce qui a changé ici n’est pas la ressource mais une de ces représentations (la représentation au format XML pour être complet).

Exposition de paramètres techniques :

Cette approche rend visible directement au client une partie de la complexité de la gestion des versions de l’API.
En effet, nous faisons apparaître dans l’URI un paramètre purement technique, le numéro de version, alors que l’URI représente la dénomination fonctionnelle et unique de la ressource.

Best practice REST

« Content negotiation »

Une autre approche qui s’appuie sur le mécanisme de négociation de contenu du protocole http réponds entre autre à ces limitations. Revenons en deux mots sur la négociation de contenu : ce mécanisme permet à un client d’une ressource web de spécifier quelle(s) représentation(s) il préfère obtenir.

Techniquement parlant cette information se trouve dans la requête http dans une entête appelée Accept header. Voici un exemple de requête avec négociation de contenu :

1
2
3

GET http://... /albums/12133
Accept : text/xml, application/json 
…

Le serveur répondra de préférence un fragment XML, s’il le gère, une structure de données JSON dans le cas contraire.
Les types définis dans l’Accept header peuvent être soit des media types standardisés soit des types personnalisés.

Versioning par Accept

Selon la philosophie REST le client spécifie dans sa requête la représentation de la ressource à laquelle il souhaite accéder. Ceci est fait au travers du mécanisme de négociation de contenu explicité ci-dessus.

Ce mécanisme permet donc de véhiculer les informations liées aux différentes versions de l’API. Le client spécifie dans le Accept Header quelles sont les versions d’une représentation d’une ressource qu’il souhaite avoir, par ordre de préférence.

La gestion des versions de service REST au travers de ce mécanisme a un prérequis : l’introduction de media types non standard.

Si nous reprenons l’exemple du versioning précédent les types créés seront :

• application/vnd.octo.music-v1+xml associé au schéma XML de la version 1 de la représentation XML de l’album
• application/vnd.octo.music-v2+xml associé au schéma XML de la version 2 de la représentation XML de l’album

Par exemple la requête pour accéder à la version 1 de la ressource album avec une représentation XML :

1
2
3
4
5
6
7

GET http://.../albums/12133
Accept : application/vnd.octo.music-v1+xml 
 
<album>
	<title>The dark side of the moon</title>
	<artist>The pink floyds</artist>
</album>

Et la requête pour accéder à la version 2 de la ressource album avec une représentation XML :

1
2
3
4
5
6
7
8
9
10
11
12

GET http://.../albums/12133
Accept : application/vnd.octo.music-v2+xml 
 
<album>
	<title>The dark side of the moon</title>
	<artists>
		<artist>Roger Waters</artist>
		<artist>David Guilmour</artist>
		<artist>Nick Mason</artist>
		<artist>Rick Wright</artist>
</artists>		
</album>

Conclusion

La principale solution apportée au problème de versioning de services REST a été d’introduire le numéro de version dans l’URI. Nous lui préférons la solution utilisant la négociation de contenu et le versioning de représentations plus que ressources.
Ceci pour plusieurs raisons :

• Le versioning via URI enfreint un des principes fondamentaux de REST : Une URI  Une ressource
• Dans la philosophie REST les échanges sont pilotés par le client, c’est le client qui sait quelle représentation il peut manipuler. Ceci autant pour le format des données (xml, json, html, …) que pour la version de ces données. Ces deux cas doivent être traités au travers du même mécanisme : la négociation de contenu et le champ Accept Header.
• La négociation de contenu permet au client de définir les versions de représentation qu’il souhaite recevoir par ordre de préférence
• Les principaux framework REST offrent des fonctionnalités natives de gestion de contenu coté client et serveur

Dans un article futur nous pourrons décrire l’architecture technique/applicative impliquée par la gestion de versions via Accept Header. Nous pourrons ainsi répondre aux questions : Comment mettre à disposition une nouvelle version d’un service ? Comment supporter coté serveur deux versions majeures d’un service en même temps ? Comment connaître les versions utilisées par les clients du service ?

Benoît Guillou & Benjamin Magnan

Suggestion d'articles :

1. Versioning des services: principes et éléments d’architecture…
2. Des principes (ou quelques idées…) REST et du Mashup
3. La stratégie de test d’une architecture REST (2/3) – Test d’intégration