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

Question

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

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

/api/v1/products 

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

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

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

Answer 1

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

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

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

Answer 2

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

1. Рекомендации по Проектирование Прагматическую RESTful API - Version via the URL, not via headers.
2. programmers.stackexchange.com: What is a recommended pattern for REST endpoints planning for foresighted changes?

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

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

Answer 3

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

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

1. Это больше explorable. Для большинства запросов вы можете просто использовать браузер, тогда как для реализации заголовка ресурса требуется более программный подход к тестированию. Однако, поскольку не все HTTP-запросы изучаются, например, POST-запросы, вы должны использовать плагин Rest Client, например Postman или Paw.URI Pro/Header Con

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

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

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

• Martin Fowler's description of the Richardson Maturity Model
• API Versioning - Pivotal Labs
• HATEAOS
• Informit.com's Article on Versioning REST Services