Discussion :

[Air P-E]

Bonjour � tous,

J'ai actuellement un projet qui utilise Web API pour fournir des services. J'aimerais la modifier pour g�rer le versioning. J'ai donc �pluch� mon meilleur ami Google et je tombe sur plusieurs blogs qui traitent ce point mais j'ai du mal � faire un choix. De ce que j'ai pu voir, il y a 3 solutions, d�finir la version dans :
- le header (champ custom ou non ?)
- une partie de l'url (par exemple : /api/v1/Book/GetAll
- query parameter (par exemple /api/Book/GetAll?v=1)

Je trouve la derni�re solution "d�gueulasse" pour pas m�cher mes mots car visuellement c'est moche, de plus �a signifie qu'il faut que je rajoute l'�l�ment "v" � chacune de mes m�thodes d�j� existante, donc modifier tout et renseigner ce champ � chaque fois.
J'ai tendance � choisir dans le header car je trouve �a propre et �a ne casse pas les URLs (existantes ou futures).
Mais je trouve que la solution dans l'url est pas mal pour tester les services rapidement dans le navigateur.

Quelle solution choisir et pourquoi ?

Merci par avance.

[chamamo]

Je me posais la question il y a un petit moment, je confirme que la derni�re proposition est d�gueulasse, le versionning dans l'URL semble �tre la meilleurs solution, mais je ne l'ai pas mis en place car tu as un service par version, dans le cas ou tu as par exemple 10 service avec 3 version, tu auras en r�alit� 30 classes � g�rer, �a reste du code dupliqu�.

J'ai opt� pour une versionning global de l'application serveur et de l'application cliente.

- Le client envoie sa requ�te HTTP avec sa version dans le header.
- Le serveur re�oit la requ�te et v�rifie si la version du client est compatible (le serveur � une version minimale du client � supporter)
- Si la version du client est inf�rieure � la version minimale support�e le serveur envoie une exception pour lui dire qu'il faut mettre � jour l'application cliente.

Maintenant le test dans l'autre sens, le client � une version minimale support�e du serveur
- dans la m�me requ�te le client envoie dans le header la version minimale support�e du serveur
- le serveur v�rifie la version re�ue du client avec sa version courante, si �a ne correspond pas une exception est envoy�e au client, cette fois-ci pour dire que la version du client est sup�rieure � la version du serveur, il faut mettre � jour le serveur.

J'esp�re que cette approche pourrait correspondre � ce que tu cherches.

[Air P-E]

Bonjour chamamo,

On se croise une fois de plus.

J'ai continu� � me renseigner (quand je pouvais) et j'ai trouv� d'autres infos ou arguments qui me font douter pour la version avec la version dans l'url.

Effectivement j'avais d�j� dans l'id�e que j'aurai du code dupliqu�. Je trouve �a normal dans le sens o� si un service est bogu�, tu es bien oblig� d'avoir une nouvelle version donc un code diff�rent (tout en gardant l'ancienne pour les clients l'utilisant encore). Au final, le code n'est pas forc�ment dupliqu�, si diff�rent, puis une version une fois finalis�e tu ne la touches plus. donc toujours qu'une seule version � g�rer.

Actuellement, nous avons une "gestion" (si on peut appeler �a comme �a) o� on d�ploie toute la partie serveur avec l'API et les Front Office mais �a signifie cr�er de nouveaux noms de domaines avec des ports diff�rents etc. enfin c'est compl�tement moche comme solution, nous sommes mal parti.

Pour le principe de tout relivrer � chaque fois, comment g�res-tu les diff�rentes version du serveur ? Tu as donc comme nous plusieurs instances � g�rer. Nous n'en avons que 2 pour le moment et �a devient d�j� ing�rable...

D'apr�s ces liens :
- http://barelyenough.org/blog/2008/05...-web-services/ et
- http://www.mnot.net/blog/2011/10/25/...ning_smackdown

la solution de la version dans l'url n'est peut-�tre pas la mieux. Qu'en penses-tu ?

[chamamo]

Oui encore une fois, le monde est petit, et ce forum l'est encore moins

Tu veux dire quoi par plusieurs instances et plusieurs domaines? tu gardes l'ancienne version quand tu d�ploies la nouvelle?

Moi j'ai une seule instance (enfin une seule version) que je met � jour si besoin, et comme j'ai expliqu� pr�c�demment si j'ai des changements qui n�cessitent une version r�cente de l'application cliente je lance une exception au client pour lui demander de mettre � jour sa version, �a me semblait moins lourd que g�rer plusieurs versions d'un m�me services, sachant que j'en ai environ 30 services pour l'instant.

[Air P-E]

Oui exactement, je garde l'ancienne version sur demande du client. Et sur le moment c'est la seule solution qui a �t� trouv�e. C'est pourquoi, nous ne pouvons pas rester dans cette situation.

Au d�but nous faisions comme toi � remplacer la version par la derni�re, mais aujourd'hui il faut g�rer la population cliente sur les diff�rentes versions.

Je suis d'accord avec l'id�e de renvoyer une exception sur une version trop ancienne mais en l�occurrence pour nous, nous n'avons actuellement que deux versions... C'est dommage !

Je pense partir sur une solution avec la version dans l'url, mais je suis pas encore d�cid�. J'ai pas eu le temps de me repencher sur la question depuis.

J'aimerais avoir d'autres avis, des retours d'exp�rience mais �a semble vide par ici...
C'est fini les vacances, revenez !

[Air P-E]

Je reviens sur le sujet.

Alors aujourd'hui j'ai pu avanc�. J'ai r�alis� un POC o� je fais appel � une version de ma web api suivant la version dans le header.
J'aimerais savoir comment je peux g�rer le cas de l'avertissement dans le retour d'une requ�te qu'il faut utiliser une version minimale de l'API (que la version que l'utilisateur utilise actuellement est obsol�te et/ou plus support�e et sera supprim�e) ?

Normalement une vielle API versionn�e n'est plus cens�e �tre modifi�e, du coup comment renvoyer dans la requ�te qu'il faut faire un upgrade sans avoir � modifier le code ?

[chamamo]

J'iamgine que tu utilies un Handler pour g�rer tout �a,

Tu peux renvoyer une exception si la version qu'il essaie d'appeler est obsol�te

un HttpResponseMessage avec HttpStatusCode.HttpVersionNotSupported comme StatusCode et une description de l'erreur:

Code :

S�lectionner tout - Visualiser dans une fen�tre � part

1
2
3
4
5
6
7
8
9
10
11
12
 
 
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
         ....
         //Si la version appelée est obsolète
         return Task<HttpResponseMessage>.Factory.StartNew(() => new HttpResponseMessage(HttpStatusCode.HttpVersionNotSupported)
            {
                ReasonPhrase = "Votre Application n'est pas à jour...."
            }, cancellationToken);
 
}

Cot� client il faut que tu r�cup�re l'erreur et l'afficher au client.
j'esp�re que j'ai bien compris ta question.

[Air P-E]

Salut Chamamo,

Oui tu as bien compris ma question et j'avais impl�ment� cette solution avant de t'avoir lu mais au moins j'ai un "tampon" de ta part sur ce que j'ai fait.

J'ai cependant un autre probl�me. Je commence � impl�menter le versioning dans mon r�el projet mais je me rends compte que beaucoup trop de choses sont versionn�es... Vraiment beaucoup...
J'ai toute mon api, toutes mes entit�s business et tout ce qui est li� � ces entit�s (Helpers qui se chargent de transformer ces entit�s en entit�s "sql", toutes mes classes de ma couche service qui font appel � la couche Repository (pas besoin d'�tre modifi�e elle)) de modifi�s. �a fait beaucoup de duplica de code (que j'avais accept�) mais beaucoup de renommage de namespace etc.

Je suis toujours surpris de voir que tu es le seul � me r�pondre Chamamo, personne d'autre n'a d� impl�menter du versioning d'API ? C'est pas possible...

[chamamo]

C'est pour �a que j'ai �vit� le versionning de chaque ApiController, je v�rifie seulement la compatibilit� globale, je v�rifie que le version du client est sup�rieure ou �gale � la version minimale support�e, et je v�rifie que la version du serveur est sup�rieure ou �gale � la version compatible avec l'application cliente, donc deux versionning.

TU peux donner plus de d�tails sur ton probl�me?

[Air P-E]

C'est pour �a que j'ai �vit� le versionning de chaque ApiController

Tu entends quoi exactement par l� ? Ce que j'ai commenc� � mettre en place versionne toute la couche API. Tous mes api controllers sont dans un namespace sp�cifique que je s�lectionne avec SelectController. Donc mon probl�me ne vient pas vraiment de l�.

je v�rifie que le version du client est sup�rieure ou �gale � la version minimale support�e

Donc tu utilises bien du versioning, mais o� ? Comment ? J'ai pas compris comment tu avais mis �a en place du coup.

je v�rifie que la version du serveur est sup�rieure ou �gale � la version compatible avec l'application cliente, donc deux versionning.

Pour ma part j'ai mis en place le versionning sur l'API justement parce que je ne veux q'une seule version du serveur. Je ne comprends pas l'int�r�t de faire du versionning si tel client est associ� � tel serveur.

Pour expliquer un peu plus, admettons que j'ai une classe AccountApiController. Dans ce controller je fais appel � une couche Service (dans un autre projet) qui se charge via la classe AccountService, de transformer mon entit� AccountBusiness en entit� AccountSql, puis fait appel � la classe AccountRepository dans la couche Repository (un autre projet) qui se charge d'effectuer la requ�te en base.

La seule couche qui n'est pas modifi�e est ma couche Repository, �tant donn� qu'elle ne travaille qu'avec des objets SQL.
Mais tout ce qui travail avec mon entit� business doit �tre versionn� puisque mon entit� business est versionn�. tu comprends mieux ?

[chamamo]

je n'aurai peu �tre pas du utiliser le mot versionning, je v�rifie plut�t la compatibilit� globale, et je ne fais pas d'association, chaque version du client est compatible avec plusieurs versions du serveur, cot� serveur aussi

Par exemple la version du client est la 1.0, elle est compatible avec la version 1.0,1.2...1.5 du serveur mais pas la 1.6, cot� serveur, si la version du serveur est la 2.0, elle est compatible avec la version 1.6, 1.5, 1.4 mais pas la version 1.3 du client.

Dans ton cas je pense que tu es oblig� de versionner la couche services, tes entit�s aussi.

Imaginons que entre deux version d'un controller tu as rajout� un champs obligatoire dans ton entit�, si tu valides par exemple les donn�es, tu dois faire une validation pour l'entit� sans ce champs et une autre qui prend en compte celui la.

[The_badger_man]

Mais tout ce qui travail avec mon entit� business doit �tre versionn� puisque mon entit� business est versionn�. tu comprends mieux ?

Tu as un exemple de versionning ici: http://www.culbertsonexchange.com/wp/?p=318

[Air P-E]

@Chamamo,
J'ai bien peur que oui, c'est d'ailleurs ce que j'ai fait. En y r�fl�chissant, je me dis que c'est pas plus mal. Lors d'un changement de version, j'ai fait un cas concret pour voir ce que �a donne : Un copier/coller du dossier version, un petit coup de ReSharper pour modifier les namespaces et le tour est jou�.
De plus la version ne changera que tr�s rarement logiquement. De toute fa�on, j'ai l'impression de ne pas avoir le choix et il n'y a pas de solutions miracles.

@The_badger_man,
Ton lien est int�ressant et je suis �tonn� de ne pas avoir pens� � une chose aussi simple !
Mais j'y vois un inconv�nient, cela implique de n'utiliser qu'une seule version de mes entit�s si je puis dire.
En effet si je rajoute des champs dans mon entit� Account (pour prendre un exemple), avec cette mise en place cela signifie que les versions pr�c�dentes se verront dot�es de ce champ en plus ce qui n'est pas normal, � mon sens. Je ne sais pas ce que tu en penses.