Как лучше всего использовать REST URI? В настоящее время у нас есть версия # в самом URI, т.е.
http://example.com/users/v4/1234/
для версии 4 этого представления.
Поддерживается ли версия в строке запроса? то есть.
http://example.com/users/1234?version=4
Или лучше управлять версией другим способом?
Я бы сказал, что сделать его частью самого URI (вариант 1) лучше всего, потому что v4 идентифицирует другой ресурс, чем v3. Параметры запроса, подобные вашему второму варианту, лучше всего использовать для дополнительной информации запроса (request), связанной с запросом, а не с ресурсом.
Не используйте URL-адреса версии, потому что...
Предполагая, что ваш ресурс возвращает какой-либо вариант приложения /vnd.yourcompany.user + xml, вам нужно создать поддержку нового типа приложения /vnd.yourcompany.userV2 + xml и магии согласования содержимого ваши клиенты v1 и v2 могут сосуществовать мирно.
В интерфейсе RESTful самое близкое, что у вас есть к контракту, - это определение типов медиа, которые обмениваются между клиентом и сервером.
URL-адреса, которые клиент использует для взаимодействия с сервером, должны предоставляться сервером, встроенным в ранее полученные представления. Единственный URL, который должен быть известен клиенту, - это корневой URL-адрес интерфейса. Добавление номеров версий в URL-адреса только имеет значение, если вы создаете URL-адреса на клиенте, что вы не предполагаете делать с интерфейсом RESTful.
Если вам нужно внести изменения в свои медиа-типы, которые сломают ваших существующих клиентов, тогда создайте новый и оставите свои URL-адреса в покое!
И для тех читателей, которые в настоящее время говорят, что это не имеет смысла, если я использую application/xml и application/json в качестве медиа-типов. Как мы должны их выпускать? Вы не. Эти медиа-типы практически бесполезны для интерфейса RESTful, если вы не разобрали их с помощью загрузки кода, и в этот момент управление версиями является спорным.
А, я снова старую свою старую хриплую шляпу.
С точки зрения РЭСТ это вообще не имеет значения. Не колбаса.
Клиент получает URI, которому он хочет следовать, и рассматривает его как непрозрачную строку. Поместите все, что вы хотите в нем, клиент не знает о такой вещи, как идентификатор версии на нем.
Что клиент знает, так это то, что он может обрабатывать тип носителя, и я советую следовать совету Даррела. Также я лично считаю, что необходимость изменения формата, используемого в спокойной архитектуре 4 раза, должна принести огромные массивные предупреждающие знаки о том, что вы делаете что-то серьезное, и полностью обходите необходимость разработки вашего типа медиа для изменения resiliance.
Но в любом случае клиент может обрабатывать документ только в том формате, который он может понять, и следить за его ссылками. Он должен знать о связях (переходы). Итак, что в URI совершенно не имеет значения.
Я лично проголосую за http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04
Совершенно корректный идентификатор, который предотвратит, чтобы какой-либо другой клиент или человек касался системы, чтобы задать вопрос, следует ли поместить v4 в начале или в конце URI (и я предлагаю, чтобы с точки зрения сервера вы не должны " t имеет 4 версии, но 4 типа носителей).
Вы не должны помещать версию в URL-адрес, вы должны поместить ее в заголовок Accept Header запроса - см. мой пост в этом потоке:
Рекомендации по управлению версиями API?
Если вы начинаете придерживаться версий в URL-адресе, вы получаете такие глупые URL-адреса, как это: http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
И есть множество других проблем, которые тоже ползут - см. мой блог: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
Эти (менее конкретные) SO-вопросы об управлении версиями REST API могут быть полезны:
Я хотел создать версии API, и я нашел эту статью очень полезной:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
Существует небольшой раздел "Я хочу, чтобы мой API был версией". Я нашел это простым и понятным. Основной задачей является использование поля Accept в заголовке для передачи информации о версии.
Я бы включил версию как необязательное значение в конце URI. Это может быть суффикс типа /V 4 или параметр запроса, как вы описали. Вы даже можете перенаправить параметр /V 4 в параметр запроса, чтобы поддерживать оба варианта.
Если службы REST требуют аутентификации перед использованием, вы можете легко связать ключ/токен API с версией API и выполнить внутреннюю маршрутизацию. Для использования новой версии API может потребоваться новый ключ API, связанный с этой версией.
К сожалению, это решение работает только для API на основе auth. Тем не менее, он сохраняет версии из URI.
Если вы используете URI для управления версиями, номер версии должен быть в URI корня API, поэтому каждый идентификатор ресурса может включать его.
Технически REST API не разбивается на изменения URL (результат унифицированного ограничения интерфейса). Он ломается только тогда, когда связанная семантика (например, специфичный для API RDF vocab) изменяется не обратным образом (редко). В настоящее время много ppl не используют ссылки для навигации (ограничение HATEOAS) и vocabs для аннотирования своих ответов REST (ограничение самоописательного сообщения), почему их клиенты ломаются.
Пользовательские типы MIME и управление версиями MIME не помогают, поскольку не переносить связанные метаданные и структуру представления в короткую строку. Ofc. метаданные и структура будут часто меняться, поэтому номер версии тоже...
Итак, чтобы ответить на ваш вопрос, лучший способ аннотировать ваши запросы и ответы с помощью vocabs (Hydra, связанные данные) и забыть управление версиями или использовать его только без обратной совместимости изменений словака (например, если вы хотите заменить vocab на другой).
Я проголосую за это в типе mime, но не в URL. Но причина не в том, что другие ребята.
Я думаю, что URL-адрес должен быть уникальным (за исключением перенаправления) для поиска уникального ресурса.
Итак, если вы принимаете /v2.0 в URL-адресах, почему это не /ver2.0 или /v2/ или /v2.0.0? Или даже -alpha и -beta? (тогда это полностью становится понятием semver)
Итак, версия в типе mime более приемлема, чем URL.