Управление версиями REST API. Каждый API имеет свою версию

15

Очень часто указывается версия API REST в URL-адресе, особенно в начале пути, например что-то вроде:

POST /api/v1/accounts
GET /api/v1/accounts/details

Тем не менее, я не видел ни одного дизайна, где версия связана с каждым API. Другими словами, мы поддерживаем версию каждого API отдельно. то есть:

POST /api/accounts/v2
GET /api/accounts/details/v3

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

Каковы недостатки использования этого стиля вместо общего стиля?

Eng.Fouad
источник

Ответы:

13

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

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

Тогда, насколько я вижу, основными минусами предложенного вами соглашения о присвоении имен локатора ресурсов являются:

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

При создании API одной из ваших основных задач является упрощение использования ...

Возможно, вы найдете лучший способ внести критические изменения или даже создать версию REST API с помощью HTTP-заголовка?

Чтобы узнать немного больше о подходе HTTP-заголовков, см. Другие ответы ниже и: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

ClemC
источник
12

Вот еще лучше подход: использовать согласование содержания для версии вашего API с Content-Typeи Acceptзаголовками:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

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

Это также позволяет поддерживать новые форматы с различной семантикой (а не только с разными версиями) на одних и тех же конечных точках. Например, размещение списка учетных записей /api/accountsможет означать создание пакета, и вам не нужно будет создавать для него отдельную конечную точку API.

разъем
источник
О боже, заголовок принятия должен быть худшим выбором сигнализации о версии. используйте заголовок версии, если можете, URL-путь, если необходимо (т.е. маршрутизацию AWS)
Ewan
@ Иван Почему? Пользовательский заголовок версии подразумевает, что разные версии являются одним и тем же ресурсом, не сообщая посредникам о том, что содержимое может отличаться. Кэширующий прокси не будет знать, использовать ли ваш заголовок, чтобы не обслуживать кэшированные ответы v1 на запросы v2.
Джек,
используйте заголовок ответа Var, если вы еще не используете no-cache для запросов API !. тип контента уже имеет значение, его суб-субподряд для личного пользования просто усложняет жизнь потребителям
Ewan
@Ewan Это то, для чего предназначена vndчасть и +синтаксис типа: чтобы указать, что это специфичный для поставщика подтип application/jsonтипа. Это именно то, для чего предназначены типы контента. Ваш ресурс доступен в нескольких форматах. Вы просите клиента выбрать формат, который он хочет. Кроме того, нет никаких причин, по которым запросы API не могут использовать стандартную семантику кэширования HTTP.
Джек,
если вы исправите ошибку в myapi v2, вы не вернете новый тип MIME.
Эван
5

Ключевым моментом является то, что если вы устанавливаете каждую конечную точку отдельно, то вы должны иметь возможность развертывать каждую конечную точку отдельно.

API обычно имеют одну версию, потому что все конечные точки находятся в одной кодовой базе и, следовательно, имеют общие зависимости и развертываются вместе.

Если вы не обновляете версию, когда вносите изменения, потому что «О, я почти уверен, что мои изменения не повлияют на это», у вас возникнут проблемы, если вы сделаете ошибку.

Кроме того, вы хотите, чтобы v1 и v2 вашего API были развернуты одновременно. Обычно это делается путем развертывания каждой версии на отдельном сервере и соответствующей маршрутизации трафика.

Если у вас нет единой версии API, это становится намного сложнее.

Ewan
источник