Pour ou contre placer la version de l'API web dans l'URL

[toc]
J’ai vu passer un billet sur Google Plus dans lequel on débattait de  :

est-il acceptable / recommandé / proscrit d’indiquer le numéro de version de l’API d’un service web directement dans l’URL.
J’ai une positionnement ferme sur cette questions, mais comme je n’aime pas imposer mon avis, je fais faire état 1) des différentes écoles et 2) d’une métaphore pour expliquer mon point de vue.

1) Il existe en effet 3 écoles :

  1. n° de version dans l’URL : https://monserviceweb.com/v1/action
  2. n° de version dans la querystring : https://monserviceweb.com/action?api=v2
  3. n° de version dans les headers HTTP de la requête client –> serveur

2) Développons maintenant ces 3 cas d’usage :

1. n° de version dans l’URL

Avantages
nul besoin de créer un objet de requêtage HTTP via un langage XYZ pour glisser le n° de version dans le header.
On peut requêter directement le service web en console via cURL ou dans un navigateur sans paramètre additionnel

Inconvénients
pas vraiment d’inconvénient si ce n’est une question de principe :
en REST une URL donne accès  une ressource. Il n’y a pas de notion d’état.

2. n° de version dans la querystring

Avantages
aucun puisque c’est une information de contexte, pas un critère de requête.
C’est un usage erroné.

Inconvénients
– documentation minimale nécessaire
– bien moins propre que placé dans l’URL
– un paramètre GET peut provoquer une mauvaise gestion du cache côté serveur.
En effet dans le principe un paramètre GET suppose l’envoi de critères d’affinage dans un contexte généraliste. Ca signifie qu’a chaque requête on crée ou recrée un nouveau contexte au lieu d’utiliser le cache d’appels récurrents.

3. n° de version dans le header HTTP

aussi appelé credentials ou encore prerequisite bref les infos qui plantent le décor, décrivent le contexte d’appel : authentification, langue, type de service, format de retour, etc…

Avantages
– Appel beaucoup mieux encapsulé donc plus propre,
– respect des directives du protocole HTTP

Inconvénients
– requiert l’usage d’un objet cURL
– moins naturel que le mode « dans l’URL »

Conclusion

Comme toujours, il n’y a pas de vérité absolue. Tout dépend comment le service web est censé être appelé.
Si on reste dans les clous des principes REST, le n° de version devrait se trouver dans le header HTTP.
Si on parle pratique, le n° de version devrait plutôt se placer dans l’URL.

La on se situe au confluent de l’esthétique et de la doctrine.
Car fonctionnellement parlant, ca ne change absolument rien, car côté serveur on peut aussi facilement récupérer l’information dans l’UR que dans le message HTTP.

Publicités

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s