Каковы плюсы и минусы для методов управления версией API

Question

В некотором примере я заметил два способа управления версией API.

Один из них использует версию в URL

/api/v1/products

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

Content-Type=application/vnd.company.v2+xml

Каковы плюсы и минусы к этим подходам? Какой какой -либо случай использования вы будете использовать каждый подход?

Answer 1

Я привык иметь номер версии в самом URL (/v1/). Я лично думаю, что это гораздо более чистый подход - таким образом, конечный пользователь (или разработчик) не нужно обрабатывать заголовки HTTP, и может просто изменить API/вызов REST, чтобы получить доступ к различным версиям API по мере необходимости.

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

Наконец, позволяет указать версию API с помощью URL -адреса позволяет простую тестирование с помощью веб -браузера. Если вы включите в заголовок HTTP в заголовке HTTP, разработчик вынужден использовать язык программирования для тестирования.

Answer 2

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

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

1. Это более эксплуатируется. Для большинства запросов вы можете просто использовать браузер, тогда как реализация заголовка ресурсов требует более программного подхода к тестированию. Однако, поскольку не все HTTP -запросы изучаются, например, Prop -запросы, вы должны использовать плагин для клиента REST Почтальон или же Лапа. Uri Pro/Header con

2. С помощью API, выполненного URVersioned, идентификация ресурсов и представление ресурса объединяется вместе. Это нарушает основные принципы отдыха; Один ресурс должен быть идентифицирован одной и только одной конечной точкой. В связи с этим выбор версий заголовка ресурсов является более академически идеалистичным. Заголовок Pro/uri con.

3. API, выполняемый URVersioned, менее подвержен ошибкам и более знаком клиентским разработчикам. Версия от URL позволяет разработчику с первого взгляда выяснить версию сервиса. F Клиентский разработчик забывает включить версию ресурса в заголовок, вы должны решить, следует ли им направить на последнюю версию (которая может вызвать ошибки при увеличении версии) или ошибке 301 (перемещенное постоянное). В любом случае есть больше путаницы для ваших более начинающих клиентских разработчиков. Uri Pro/Header con
4. URI Versioning подходит для укрытия нескольких версий в одном и том же приложении. В этом случае вам не нужно дальнейшее развитие вашей структуры. Примечание. Если вы сделаете это, ваша структура каталогов, скорее всего, будет содержать значительное количество дубликата кода в каталоге V2. Кроме того, развертывание обновлений требует перезапуска системы - поэтому этого метода следует избегать, если это возможно. Uri Pro/Header con.
5. Легче добавить версию в заголовки HTTP для существующего проекта, который еще не имел внимания на версий с самого начала. Заголовок Pro/uri con.
6. Согласно RMM Уровень 3 Принцип REST: Hypermedia Controls, Вы должны использовать заголовки HTTP Accept и Content-Type для обработки версий данных, а также описания данных. Заголовок Pro/uri con.
7. Когда вы помещаете версию в URL -адрес, ваши клиенты должны координировать изменение своего кода (или, если они умны, их конфигурация), на новый API. Заголовок Pro/uri con.

Вот несколько полезных ссылок, если вы хотите сделать дальнейшее чтение:

• Описание Мартина Фаулера модели зрелости Ричардсона
• Версия API - ключевые лаборатории
• Hateaos
• Статья Informit.com о службах RESTERS REST

Answer 3

Лучше использовать версию в URL. Я искал это некоторое время назад и наткнулся на следующие 2 ресурса, которые обсуждают RESTFUL API Дизайн в натуральную величину.

1. Лучшие практики для разработки прагматического API RESTFUL - Версия через URL, а не через заголовки.
2. Программисты.stackexchange.com : Что является рекомендуемой шаблоном для планирования конечных точек REST для предзнаменных изменений?

TL; DR Ответ: Использование версии # в URL -адресе является рекомендуемым подходом.

Некоторые из самых сквозных API, с которыми я сталкивался- Instagram API а также Stackoverflow.com API - оба используют этот подход к версии API.