Quels sont les avantages et les inconvénients des méthodes de version de l'API

Question

J'ai remarqué dans certains exemple deux façons de verser une API.

L'un d'eux utilise une version dans l'URL

/api/v1/products

L'autre utilise l'en-tête de type de contenu et l'en-tête d'accepter pour marquer la version API pour les données envoyées au serveur

Content-Type=application/vnd.company.v2+xml

Quels sont les avantages et les inconvénients de ces approches? Quel est le cas d'utilisation où vous utiliserez chaque approche?

Answer 1

J'ai l'habitude d'avoir le numéro de version dans l'URL lui-même (/ v1 /). Je pense personnellement qu'il s'agit d'une approche beaucoup plus propre - de cette façon, l'utilisateur final (ou le développeur) n'a pas besoin de gérer les en-têtes HTTP, et peut simplement modifier l'API / appel de repos pour accéder à différentes versions de l'API au besoin.

Je pense qu'il est également possible que certaines des API HTTP là-bas dans différentes langues aient un support complet pour les en-têtes HTTP, vous faites donc toujours pour rendre l'API le plus facilement disponible pour l'utilisateur final. La réécriture de l'URL est la manière la plus simple, et elle devrait fonctionner avec tout ce qui prend en charge HTTP.

Enfin, permettre à la version API d'être spécifiée à l'aide de l'URL permet un test simple à l'aide d'un navigateur Web. Si vous incorporez le versioning dans un en-tête HTTP, le développeur est obligé d'utiliser un langage de programmation pour effectuer des tests.

Answer 2

Les deux mécanismes sont valides. Vous devez connaître votre consommateur pour savoir quel chemin suivre. En général, travailler avec les entreprises et les gens à l'esprit académique a tendance à pointer des développeurs vers le versioning d'en-tête des ressources. Cependant, si vos clients sont des entreprises plus petites, l'approche du versioning URL est plus largement utilisée.

Voici les avantages et les inconvénients que je pourrais trouver (je suis sûr qu'il y en a plus, et certains des inconvénients ont un travail autour de non mentionné ici)

1. C'est plus explorable. Pour la plupart des demandes, vous pouvez simplement utiliser un navigateur, tandis que la mise en œuvre de l'en-tête des ressources nécessite une approche plus programmatique des tests. Cependant, parce que toutes les demandes HTTP ne sont pas explorables, par exemple, les demandes de publication, vous devez utiliser un plugin client REST comme Facteur ou Patte. Uri pro / en-tête con

2. Avec une API uri-évoquée, l'identification des ressources et la représentation de la ressource sont regroupées. Cela viole les principes de base du repos; Une ressource doit être identifiée par un et un seul point de terminaison. À cet égard, le choix du versioning d'en-tête des ressources est plus idéalement idéaliste. En-tête pro / uri con.

3. Une API uri-voncée est moins sujette aux erreurs et plus familière aux développeurs de clients. Le versioning par URL permet au développeur de déterminer la version d'un service en un coup d'œil. F Le développeur client oublie d'inclure une version de ressource dans l'en-tête, vous devez décider s'il doit être dirigé vers la dernière version (ce qui peut entraîner des erreurs lors de l'incrémentation de la version) ou une erreur 301 (déplacée permanent). Quoi qu'il en soit, il y a plus de confusion pour vos développeurs de clients plus novices. Uri pro / en-tête con
4. Le versioning URI se prête à des versions de plusieurs versions dans la même application. Dans ce cas, vous n'avez pas à développer votre cadre. Remarque: Si vous le faites, votre structure de répertoire contiendra très probablement une quantité substantielle de code en double dans le répertoire V2. De plus, le déploiement de mises à jour nécessite un redémarrage du système - ainsi cette technique doit être évitée si possible. Uri pro / en-tête con.
5. Il est plus facile d'ajouter le versioning aux en-têtes HTTP pour un projet existant qui n'avait pas déjà le versioning à l'esprit de sa création. En-tête pro / uri con.
6. Selon le RMM Niveau 3 Rest Principe: Hypermedia Controls, vous devez utiliser les en-têtes HTTP Accepter et Content-Type pour gérer le versioning des données ainsi que pour décrire les données. En-tête pro / uri con.
7. Lorsque vous mettez la version dans l'URL, vos clients doivent coordonner un changement de leur code (ou s'ils sont intelligents, leur configuration), vers la nouvelle API. En-tête pro / uri con.

Voici quelques liens utiles si vous voulez faire quelques lectures supplémentaires:

• La description de Martin Fowler du modèle de maturité de Richardson
• Versioning API - laboratoires pivots
• Hateaos
• Article d'Offit.com sur les services de repos des versions

Answer 3

Mieux vaut utiliser la version dans URL. Je cherchais cela il y a quelque temps et je suis tombé sur les 2 ressources suivantes qui discutent Conception d'API RESTFul Enfin.

1. Meilleures pratiques pour concevoir une API RESTful pragmatique - Version via l'URL, pas via des en-têtes.
2. programmers.stackexchange.com : Qu'est-ce qu'un modèle recommandé pour la planification des points de terminaison de repos pour les changements prévus?

TL; DR RÉPONSE: L'utilisation de la version # dans l'URL est une approche recommandée.

Certains des API les plus conçus que j'ai rencontrés - API Instagram et API stackoverflow.com - Les deux utilisent cette approche du versioning d'API.