Quelle est la meilleure façon de versionner les URI REST ? Actuellement, nous avons une version # dans l'URI lui-même, c'est-à-dire.
http://example.com/users/v4/1234/pour la version 4 de cette représentation.
La version doit-elle être incluse dans la chaîne de requête ?
http://example.com/users/1234?version=4Ou bien le versioning est-il mieux réalisé d'une autre manière ?
N'utilisez pas de versions d'URL, car ...
En supposant que votre ressource renvoie une variante de application/vnd.yourcompany.user+xml, il vous suffit de créer un support pour un nouveau type de média application/vnd.yourcompany.userV2+xml et, par la magie de la négociation de contenu, vos clients v1 et v2 pourront coexister pacifiquement.
Dans une interface RESTful, ce qui se rapproche le plus d'un contrat est la définition des types de médias qui sont échangés entre le client et le serveur.
Les URL que le client utilise pour interagir avec le serveur doivent être fournies par le serveur, intégrées dans des représentations précédemment récupérées. La seule URL qui doit être connue par le client est l'URL racine de l'interface. L'ajout de numéros de version aux urls n'a de valeur que si vous construisez des urls sur le client, ce que vous n'êtes pas censé faire avec une interface RESTful.
Si vous devez apporter à vos types de médias une modification qui risque de perturber vos clients existants, créez-en un nouveau et ne touchez pas à vos urls !
Et pour les lecteurs qui disent actuellement que cela n'a aucun sens si j'utilise application/xml et application/json comme types de médias. Comment sommes-nous censés faire ces versions ? Vous ne l'êtes pas. Ces types de médias sont pratiquement inutiles pour une interface RESTful, à moins que vous ne les analysiez en utilisant le téléchargement de code, auquel cas le versionnement est un point discutable.
Pour répondre à ces points. 1. Vous ne cassez pas les liens perma, car les permaliens renvoient à une version spécifique. 2. Si tout est versionné, ce n'est pas un problème. Les anciennes urls peuvent encore fonctionner. Idéalement, vous ne voudriez pas qu'une URL de version 4 renvoie une association à une ressource de version 3. 3. Peut-être
Imaginez que, lorsque vous passez à une nouvelle version d'un navigateur web, tous vos signets favoris soient détruits ! N'oubliez pas que, conceptuellement, l'utilisateur enregistre un lien vers une ressource, et non vers une version d'une représentation d'une ressource.
@Darrel, je suis d'accord avec tout ce que vous avez écrit sauf pour le commentaire sur les types de médias xml/json qui sont inutiles pour les interfaces RESTful. Pouvez-vous préciser ? Je ne comprends pas ce que tu veux dire...
Je dirais que l'intégrer à l'URI lui-même (option 1) est la meilleure solution car la v4 identifie une ressource différente de la v3. Les paramètres de requête, comme dans votre deuxième option, peuvent être utilisés pour transmettre des informations (de requête) supplémentaires liées à l'URI. demande plutôt que le ressource .
La question est de savoir si c'est d'une RESSOURCE différente dont il est question. Ou d'une représentation différente de cette ressource ? REST fait-il une distinction entre la représentation et la ressource ?
@Cheeso - Le PO indique qu'il s'agit d'une représentation différente plutôt que d'une ressource différente, d'où ma réponse.
Ah, je remets mon vieux chapeau de grincheux.
Du point de vue de ReST, ça n'a pas d'importance du tout. Pas une saucisse.
Le client reçoit une URI qu'il veut suivre, et la traite comme une chaîne opaque. Vous pouvez y mettre ce que vous voulez, le client dispose de pas de la connaissance d'une chose telle qu'un identifiant de version sur elle.
Ce que le client sait, c'est qu'il peut traiter le type de média, et je lui conseille de suivre les conseils de Darrel. De plus, je pense personnellement que le fait d'avoir à changer 4 fois le format utilisé dans une architecture reposante devrait déclencher d'énormes signaux d'avertissement indiquant que vous faites quelque chose de très mal et que vous n'avez pas besoin de concevoir votre type de média pour résister aux changements.
Mais dans tous les cas, le client ne peut traiter qu'un document dont le format est compréhensible pour lui et suivre les liens qu'il contient. Il doit connaître les relations entre les liens (les transitions). Ce qui se trouve dans l'URI n'est donc absolument pas pertinent.
Personnellement, je voterais pour http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04
Un identifiant parfaitement valide qui empêchera tout autre développeur de client ou toute personne touchant au système de se demander s'il faut mettre v4 au début ou à la fin d'un URI (et je suggère que, du point de vue du serveur, il ne faut pas avoir 4 versions, mais 4 types de médias).
Que se passe-t-il si la représentation doit être modifiée de manière significative et qu'elle n'est pas rétrocompatible ?
En concevant votre type de média de manière extensible, par exemple en utilisant des espaces de noms et un xsd extensible, ou des formats xml existants comme atom, cela devrait pouvoir être évité. Si vous devez vraiment le faire, un autre type de média est la solution.
Vous ne devez PAS mettre la version dans l'URL, mais dans l'en-tête d'acceptation de la demande - voir mon message sur ce fil de discussion :
Meilleures pratiques pour le versionnement des API ?
Si vous commencez à coller des versions dans l'URL, vous vous retrouvez avec des URL idiotes comme celle-ci : http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
Et il y a un tas d'autres problèmes qui se glissent aussi - voir mon blog : http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
Désolé, mais je ne pense pas que vous vous retrouviez avec des URLs stupides comme ça. Vous liez les numéros de version à une ressource particulière ou (pire) à une représentation particulière. Ce serait stupide, IMO. Il s'agit plutôt de versionner l'API, de sorte qu'il n'y a jamais plus d'une version dans l'URI.
Prograide est une communauté de développeurs qui cherche à élargir la connaissance de la programmation au-delà de l'anglais.
Pour cela nous avons les plus grands doutes résolus en français et vous pouvez aussi poser vos propres questions ou résoudre celles des autres.
1 votes
Duplicata possible de Meilleures pratiques pour le versionnement des API ?