REST api versioning (seule version la représentation, pas la ressource elle-même)

https://stackoverflow.com/questions/2024600

19-09-2019
|

Question

J'ai regardé Les meilleures pratiques pour l'API versioning , mais je ne suis pas tout à fait convaincu de la réponse, donc je suis en doute la partie de versionnage à nouveau avec un exemple plus précis. J'ai deux URIs (une avec versioning dans le cadre de l'URI et un sans):

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123

J'ai mes doutes si le premier lien exprime l'idée de repos. Je trouve déroutant http://xxxx/v1/user/123 car il suggère qu'il y aura une version api plus un jour comme http://xxxx/v2/user/123. Mais cela n'a pas de sens en termes REST, la version api lui-même est HTTP 1.0 ou 1.1, qui est déjà envoyé dans la requête HTTP. Cette REST vue centrée sur des ressources diffère très d'autres interfaces api-comme des interfaces Java SOAP ou (où il est fréquent d'avoir des versions api-en noms qualifiés).

Au repos, la seule chose où versioning est logique est la représentation de cette ressource (par exemple les nouveaux champs sont ajoutés ou supprimés). Ce versioning appartient à la partie de la négociation du contenu comme:

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

On pourrait faire valoir que telle version négociation de contenu pourrait faire partie de l'URI dans le chemin, mais je trouve contre-intuitif, parce que vous pourriez-avec différents URIs pour la même ressource et doivent maintenir réoriente à un moment donné.

Pour résumer: En REST URIs il n'y a pas api-versioning, ne versionnage de la représentation de la ressource. Représentation version information appartient à la négociation de contenu (comme queryParam ou HTTP « Accepter »).

Que pensez-vous? Où les choses vous êtes en désaccord / d'accord?

La solution

Je suis complètement d'accord; un URI exprime l'identité, l'identité ne change pas quand on introduit une nouvelle version. Il pourrait y avoir de nouveaux concepts pour URIs supplémentaires, bien sûr, et peut rediriger les URIs existants ... mais y compris une « v2 » dans l'URI odeurs RPCish pour moi.

Notez que cela n'a rien à voir avec REST, vraiment, comme dans une perspective de repos, il est tout juste caractères.

Autres conseils

peut écouter un en-tête de requête HTTP X-API-Version. Si l'en-tête existe, le serveur doit utiliser cette version de l'API. Si l'en-tête n'existe pas, le serveur peut utiliser la dernière version de l'API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Pour ce qu'elle vaut, je suis d'accord avec vous Manuel. Vous pouvez voir mon raisonnement dans cette Comment la version REST URIs

Il y a beaucoup de gens qui semblent être en désaccord, mais je ne vous inquiétez pas. Ce que votre URL ressemble n'a pas vraiment un grand impact sur votre client tant que vous respectez la contrainte hypertexte.

Je suis d'accord que vous ne voulez pas voir les versions dans les URIs des ressources présentées dans votre API. Cela les rend pas « cool ». Aussi reconnaissent que ce sont les représentations les plus susceptibles de changer.

Cependant, il ne soulève alors la question de ce qui se passe lorsque vous modifiez le contenu d'une représentation particulière. Par exemple, si votre représentation JSON originale d'un frobnitz est

{"x": "bam", "y": "hello"}

et que vous voulez ajouter un champ « z » vous pouvez sentir que le client doit avoir une certaine prise de conscience que nous sommes maintenant sur la version 2 d'une sorte de système de données.

Je ne suis pas sûr. Je pense que vous avez quelques options:

Faites vos clients flexibles face à une évolution en douceur des représentations. Dans l'exemple ci-dessus nous générons encore un dictionnaire JSON.
Si vous devez, mettre une version dans la représentation elle-même (un champ de version dans cet exemple). Ce faisant vous déclarer effectivement une sous-représentation dans le type de contenu JSON. Je pense que c'est assez limitant cependant.
Utilisez vos propres types MIME et la version: les application / x-my-spéciale json1.0, application / x-my-json1.1 spécial. Cela vous permet de versionner vos représentations indépendamment les uns des autres. Encore une fois, avec celui-ci vous faites une demande importante sur vos clients de savoir ce qui se passe.

En général, je pense que vous souhaitez optimiser votre API et vos représentations pour les clients que vous ne vous êtes pas inventées; ceux que d'autres personnes vont créer à la découverte de vos ressources. Je crois que ce qui est utile, même dans le cas où vous faites quelque chose qui est privé, parce qu'il construit dans une contrainte de conception utile qui aidera à rendre votre système plus robuste.

Je trouve http: // xxxx / v1 / user / 123 déroutante, car elle suggère qu'il y sera une version plus api jour comme http: // xxxx / v2 / user / 123

Il ne suggère pas que - mais vous avez cette capacité à l'avenir

Mais cela n'a pas de sens dans REST termes, la version api lui-même est HTTP 1,0 ou 1,1, ce qui est déjà envoyée dans la requête HTTP.

La version de votre API et la version de HTTP que vous utilisez pour faire des demandes ne doivent pas être égaux.

On pourrait faire valoir que telle version La négociation du contenu pourrait faire partie de l'URI dans le chemin, mais je trouve contre-intuitif, parce que vous pourriez fin avec différents URIs pour la même ressource et doivent maintenir réoriente à un moment donné.

Son bien d'avoir la version en tant que paramètre URI que vous avez fait preuve.

http: // xxx / user / 123 v = 1 -> pour Perma -liens / hyperliens

Une autre approche pourrait être de dire que « une représentation a plusieurs API »:

http://xxx/user/123/api/1.json

Et si vous le souhaitez, vous pouvez retourner la représentation en utilisant la dernière API lors de la demande comme ceci:

http://xxx/user/123.json

Personnellement, j'aime d'autres solutions mieux, mais cela est une autre approche que je ne l'ai pas vu ici encore suggéré.

Pour REST, ce que la plupart des réponses oublient est l'élément de données. Je suppose que l'API de versions multiples Partageons toujours la même couche de données. Cela signifie que la couche de données vous oblige à penser d'une manière compatible vers l'arrière. De grands changements qui ont à faire ne sont possibles que si vos modifications de l'API d'une manière compatible vers l'arrière. En pratique, cela signifie que les propriétés supplémentaires sont ajoutées en silence à vos entités en utilisant deprecation par date dans votre document API pour indiquer quand quelque chose sera supprimé. Idéalement, vous utilisez un système de registre avec l'adresse e-mail de vos API utilisateurs clés, de sorte que vous pouvez les informer de dévalorisation dans un certain champ (à la Facebook) .Par conséquent, je ne pense pas que vous devez spécifier une version nulle part.

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow