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

Очень часто указывается версия 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.

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

То, что вы называете одиночными 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/

Вот еще лучше подход: использовать согласование содержания для версии вашего 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.

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

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

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

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

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