REST Api и семантическое управление версиями - PullRequest
Новая
       55

REST Api и семантическое управление версиями

0 голосов
/ 24 октября 2019

Моя команда создала несколько API-интерфейсов и теперь общедоступна. Теперь мы добавляем функции к одному из наших API, которые будут бесперебойными для наших существующих клиентов, так что это будет считаться незначительным обновлением в соответствии с https://semver.org. Теперь мы понимаем, что хотим следовать принципам семантического контроля версий. Мы также делаем версии URI. Допустим, мы находимся на v1.0.0, и теперь мы должны обновить его до v1.1.0. По совету других постов, если мы решили ожидать только основную версию в маршруте, например, /api/v1/animals, но все клиенты будут обновлены до последней версии v1, так как она должна быть обратно совместимой, это говорит мне, что семантическаяуправление версиями осуществляется внутренне. Как это обычно обрабатывается? У нас есть приложение Rails, и если наша структура была такой: 

/controllers
  /api
    /v1.0.0
      animals_controller.rb

Если мы обновились до вспомогательной версии v1.1.0, следует ли нам создать новую папку v1.1.0 с новым файлом animals_controller.rb внутриЭто? Или, если изменения обратно совместимы, то должны ли они быть в файле animals_controller.rb внутри v1.0.0? Но если мы сделаем это, тогда действительно, не должно ли это быть просто: 

/controllers
  /api
    /v1
      animals_controller.rb

? У меня создается впечатление, что семантическое управление версиями является внутренним и не обязательно должно быть раскрыто потребителям ... Это просто вопрос использования тегов?

1 Ответ

0 голосов
/ 24 октября 2019

Причиной создания настоящего API-интерфейса REST является возможность развития ... «v1» - это средний палец для ваших клиентов API, указывающий RPC / HTTP (не REST) ​​- Fielding, 2013

Частью REST является то, что идентификаторы (URI) могут быть просто идентификаторами, а протокол приложения домена описывается гипермедиа.

Так что да, если вы "выполнение REST ", тогда семантически версионный URI - пустая трата времени каждого (поскольку для клиентов это непрозрачно. Помните, что сокращатели URI работают .)

ГдеУправление версиями имеет значение в семантике связей и типов медиа. Попытка внести обратно несовместимые изменения приводит к огромному беспорядку, поэтому много работы проделано для обеспечения совместимости (которая по-прежнему HTML5 text/html), а нарушение совместимости предпочтительно реализуется путем введения нового имени (text/not-html-anymore).

...