Как вариант отдыха Урис

Не делайте URL-адреса версий, потому что ...

• вы нарушаете ссылок
• изменения url будут распространяться как болезнь через ваш интерфейс. Что вы делаете с представлениями, которые не изменились, но указывают на представление, что есть? Если вы измените url-адрес, вы сломаете старых клиентов. Если вы оставите url-адрес, ваши новые клиенты могут не работать.
• Версионные типы носителей-это гораздо более гибкое решение.

предполагая, что ваш ресурс возвращает некоторый вариант приложения / vnd.ваша компания.user + xml все, что вам нужно сделать, это создать поддержку для нового приложения/vnd.ваша компания.тип носителя userV2+xml и через волшебство согласования содержания ваши клиенты v1 и v2 могут сосуществовать мирно.

в интерфейсе RESTful самое близкое, что у вас есть к контракту,-это определение типов носителей, которые обмениваются между клиентом и сервером.

URL, которые клиент использует для взаимодействия при этом сервер должен быть обеспечен сервером, встроенным в ранее полученные представления. Единственным URL-адресом, который должен быть известен клиенту, является корневой URL-адрес интерфейса. Добавление номеров версий в URL-адреса имеет значение только в том случае, если вы создаете URL-адреса на клиенте, что вы не должны делать с интерфейсом RESTful.

Если вам нужно внести изменения в ваши медиа-типы, которые сломают ваши существующие клиенты, то создайте новый и оставьте свои URL-адреса один!

и для тех читателей, которые в настоящее время говорят, что это не имеет смысла, если я использую application/xml и application/json в качестве медиа-типов. Как мы должны версии? А ты нет. Эти медиа-типы в значительной степени бесполезны для интерфейса RESTful, если вы не анализируете их с помощью загрузки кода, и в этот момент управление версиями является спорным вопросом.

Ах, я снова надеваю свою старую сердитую шляпу.

с точки зрения отдыха, это вообще не имеет значения. Не сосиска.

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

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

но в любом случае, клиент может обрабатывать только документ с форматом, который он может понять, и следовать ссылкам в нем. Он должен знать о связи (переходы). Так что то, что находится в URI, совершенно не имеет значения.

I лично проголосовал бы за http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04

совершенно действительный идентификатор, который предотвратит любого дальнейшего разработчика клиента или человека, прикасающегося к системе, чтобы спросить, следует ли ставить v4 в начале или в конце URI (и я предлагаю, чтобы с точки зрения сервера у вас было не 4 версии, а 4 типа носителей).

вы не должны помещать версию в URL, вы должны поместить версию в заголовок Accept запроса-см. мой пост в этой теме:

рекомендации по управлению версиями 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

эти (менее конкретные) вопросы о REST API versioning могут быть полезны:

• управление версиями RESTful services?
• рекомендации по управлению версиями REST API веб-службы

Если службы REST требуют проверки подлинности перед использованием, вы можете легко связать ключ/маркер API с версией API и выполнить маршрутизацию внутри. Для использования новой версии API может потребоваться новый ключ API, связанный с этой версией.

к сожалению, это решение работает только для API на основе auth. Тем не менее, он сохраняет версии из URI.

Я хотел создать версионные API, и я нашел эту статью очень полезной:

http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http

есть небольшой раздел "я хочу, чтобы мой API был версионным". Я нашел его простым и легким для понимания. Суть заключается в использовании поля Accept в заголовке для передачи информации о версии.

Я бы включил версию в качестве необязательного значения в конце URI. Это может быть суффикс типа /V4 или параметр запроса, как вы описали. Вы даже можете перенаправить /V4 в параметр запроса, чтобы поддерживать оба варианта.

Если вы используете URI для управления версиями, то номер версии должен быть в URI корня API, поэтому каждый идентификатор ресурса может включать его.

технически REST API не нарушает изменения URL (результат ограничения единого интерфейса). Он ломается только тогда, когда связанная семантика (например, специфичный для API RDF vocab) изменяется не обратно совместимым образом (редко). В настоящее время многие ppl не используют ссылки для навигации (ограничение HATEOAS) и vocabs для аннотирования их ответы остальных (описательные ограничения сообщений), поэтому их клиенты перерыва.

пользовательские типы MIME и управление версиями типа MIME не помогают, потому что помещение связанных метаданных и структуры представления в короткую строку не работает. Конвертер ofc. метаданные и структура будут часто меняться, и поэтому номер версии тоже...

поэтому, чтобы ответить на ваш вопрос, лучший способ аннотировать ваши запросы и ответы с помощью vocabs (Гидра,общие сведения) и забыть управление версиями или использовать его только с помощью не обратно совместимых изменений vocab (например, если вы хотите заменить vocab другим).

Я голосую за это в типе mime, но не в URL. Но причина не такая, как у других ребят.

Я думаю, что URL-адрес должен быть уникальным (за исключением тех, переадресовывает) для определения уникального ресурса. Так что, если вы принимаете /v2.0 в URL, почему это не /ver2.0 или /v2/ или /v2.0.0? Или даже -alpha и -beta? (тогда это полностью становится понятием semver)

таким образом, версия в типе mime более приемлема, чем URL.

существует 4 различных подхода к управлению версиями API:

• добавление версии в путь URI:

  http://example.com/api/v1/foo
  
  http://example.com/api/v2/foo
  

  когда у вас есть нарушение изменения, вы должны увеличить версию, как: v1, v2, v3...

  вы можете реализовать контроллер в своем коде следующим образом:

  @RestController
  public class FooVersioningController {
  
  @GetMapping("v1/foo")
  public FooV1 fooV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping("v2/foo")
  public FooV2 fooV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• управление версиями параметров запроса:

  http://example.com/api/v2/foo/param?version=1
  http://example.com/api/v2/foo/param?version=2
  

  в параметр version может быть необязательным или обязательным в зависимости от того, как вы хотите использовать API.

  реализация может быть похожа на это:

  @GetMapping(value = "/foo/param", params = "version=1")
  public FooV1 paramV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping(value = "/foo/param", params = "version=2")
  public FooV2 paramV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• передача пользовательского заголовка:

  http://localhost:8080/foo/produces
  

  С заголовка:

  headers[Accept=application/vnd.company.app-v1+json]
  

  или:

  headers[Accept=application/vnd.company.app-v2+json]
  

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

  возможная реализация:

  @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
  public FooV1 producesV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
  public FooV2 producesV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• изменение имен хостов или использование шлюзов API:

  по существу, вы перемещаете API от одного имени хоста к другому. Вы даже можете просто назвать это здание новым API для тех же ресурсов.

  кроме того, вы можете сделать это с помощью шлюзов API.