Как управлять версиями REST URI

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

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

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

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

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

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

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

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

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

С точки зрения ReST это вообще не имеет значения. Не колбаса.

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

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

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

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

Вы НЕ должны указывать версию в 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

Эти (менее конкретные) вопросы SO о версиях REST API могут быть полезны:

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

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

• #P2#

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

  <цитата> #P3# #P4#

  @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"));
  }
  

• #P5#

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

  #P6#

  #P7#

  @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]
  

  or:

  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"));
  }
  

• #P12# <цитата> #P13# #P14#

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

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

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

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

К сожалению, это решение работает только для API на основе аутентификации. Однако он хранит версии вне URI.

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

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

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

Итак, чтобы ответить на ваш вопрос, лучше всего аннотировать ваши запросы и ответы словарями (Hydra, связанные данные) и забудьте о версиях или используйте их только для необратимых изменений словарного запаса (например, если вы хотите заменить словарь другим).

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

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

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

Таким образом, версия в MIME-типе более приемлема, чем URL-адрес.