REST api versioning (только версия - представление, а не сам ресурс)

Я просмотрел Рекомендации по управлению версиями API?, но я не совсем уверен в ответе, поэтому я снова задаюсь вопросом о версии с более конкретным пример. У меня есть два URI (один с версией как часть URI и один без):

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

У меня возникают сомнения в том, что первая ссылка выражает идею REST. Я нахожу http://xxxx/v1/user/123 запутанным, так как это говорит о том, что когда-нибудь будет более высокая версия api, например http://xxxx/v2/user/123. Но это не имеет смысла в терминах REST, сама версия api - HTTP 1.0 или 1.1, которая уже отправлена внутри HTTP-запроса. Этот ориентированный на ресурсы ресурс REST сильно отличается от других api-интерфейсов, таких как SOAP или Java-интерфейсы (где обычно имеют api-версии в квалифицированных именах).

В REST единственное, что имеет смысл в версии, - это представление этого ресурса (например, новые поля добавляются или удаляются). Это управление версиями относится к части согласования контента, например:

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

Можно также утверждать, что такое согласование содержимого версии может быть частью URI внутри пути, но я нахожу его интуитивно понятным, потому что вы могли бы получить различные URI для одного и того же ресурса и должны поддерживать перенаправления на некоторая точка.

Подводя итог: в URI REST нет api-версий, только версия представления ресурсов. Представленная версия-информация относится к контенту-согласованию (в качестве запросаParam или HTTP "Accept" ).

Как вы думаете? В каких вещах вы не согласны/согласны?

Ответ 1

Я полностью согласен; URI выражает личность, идентичность не изменяется при введении новой версии. Конечно, могут существовать новые URI для дополнительных понятий, и существующие URI могут перенаправляться... но в том числе "v2" в URI пахнет RPCish мне.

Обратите внимание, что это не имеет никакого отношения к REST, действительно, поскольку с точки зрения REST это все просто символы.

Ответ 2

Вы можете прослушать заголовок запроса X-API-Version HTTP. Если заголовок существует, сервер должен использовать эту версию API. Если заголовок не существует, сервер может использовать последнюю версию 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" } }
<

Ответ 3

Для чего это стоит, я согласен с тобой Мануэль. Вы можете увидеть мои рассуждения в этом вопросе Как изменить REST URI

Есть много людей, которые, похоже, не согласны, но я не стал бы волноваться. То, как выглядит ваш URL-адрес, действительно не оказывает большого влияния на вашего клиента, если вы уважаете гипертекстовое ограничение.

Ответ 4

Я согласен с тем, что вы не хотите видеть версии в URI ресурсов, представленных в вашем API. Это делает их не "крутыми". Также согласитесь с тем, что это наиболее вероятные изменения.

Однако он поднимает вопрос о том, что происходит, когда вы меняете содержимое определенного представления. Например, если ваше исходное JSON-представление frobnitz равно

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

и вы хотите добавить поле "z", вы можете почувствовать, что у клиента должно быть некоторое представление о том, что мы сейчас находимся на версии 2 какой-либо схемы данных.

Я не уверен в этом. Я думаю, у вас есть несколько вариантов:

Сделайте ваши клиенты гибкими в лицо, слегка меняя представления. В приведенном выше примере мы все еще создаем словарь JSON.
Если нужно, поместите версию в самом представлении (поле версии в этом примере). Таким образом, вы фактически объявляете субпредставление в контенте типа JSON. Я считаю, что это довольно ограничено.
Используйте свои собственные типы MIME и их версию: application/x-my-special-json1.0, application/x-my-special-json1.1. Это позволяет вам изменять ваши представления независимо друг от друга. Опять же, с этим вы делаете значительный спрос на своих клиентов, чтобы знать, что происходит.

В целом, я думаю, вы хотите оптимизировать свой API и свои представления для клиентов, которые вы сами не изобрели; которые другие люди создадут при обнаружении ваших ресурсов. Я считаю, что это полезно даже в том случае, если вы делаете что-то частное, потому что оно создает полезное конструктивное ограничение, которое поможет сделать вашу систему более надежной.

Ответ 5

Я нахожу http://xxxx/v1/user/123путают, поскольку это говорит о том, что там когда-нибудь будет выше api-версия например http://xxxx/v2/user/123

Это не предполагает, что - однако у вас есть эта способность в будущем.

Но это не имеет смысла в REST термины, сама версия api - это HTTP 1.0 или 1.1, который уже отправлен внутри HTTP-запроса.

Версия ВАШЕГО API и версия HTTP, которую вы используете для выполнения запросов, не должны быть равны.

Можно также утверждать, что такая версия Консолидация контента может быть частью URI внутри пути, но я нахожу его контринтуитивный, потому что вы могли бы в конечном итоге с различными URI для тот же ресурс и должен поддерживать перенаправляет в какой-то момент.

Хорошо, чтобы версия была параметром URI, как вы показали.

http://xxx/user/123?v=1 → для перма-ссылок/гиперссылок

Ответ 6

Другой подход может состоять в том, чтобы сказать, что "одно представление имеет несколько API":

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

И если вы хотите, вы можете вернуть представление с использованием новейшего API при запросе:

http://xxx/user/123.json

Лично мне лучше нравятся другие решения, но это еще один подход, который я еще не видел здесь.

Ответ 7

Для REST, что большинство ответов забывают, это элемент данных. Я предполагаю, что несколько версий API по-прежнему используют один и тот же уровень данных. Это означает, что слой данных заставляет вас думать обратным образом. Большие изменения, которые необходимо сделать, возможны только в том случае, если ваш API изменяется обратно совместимым образом. На практике это означает, что дополнительные свойства добавляются тихо к вашим сущностям, в то время как использование устаревания по дате в вашем документе API указывает, когда что-то будет удалено. В идеале вы используете схему регистрации с адресом электронной почты ваших пользователей ключа API, поэтому вы можете уведомить их об отказе в определенной области (a la Facebook). Поэтому я не думаю, что вам нужно указывать версию где угодно.