Версионирование HTTP API
#Версионирование HTTP API
Business - адаптируется, API - версионируется.
Для того чтобы быть постоянно восстребованным клиентами, бизнесс должен постоянно адаптироваться. Соответсвенно программное обеспечение которое реализует бизнесс модели развиваться и адаптироваться для того чтобы удволтеворять нуждам клиентов. Неотъемлимой частью такого ПО являются API которые позволяют клиентам программно интегрироваться с сервисами. К сожалению невсегда можно создать API который изначально будет достаточно гибким для того чтобы развиваться и при этом не нарушать контракт с существующими клиентами. Обычным подходом является создание одновременно существующих нескольких версий API, таким образом чтобы существующие клиенты могли продолжать использовать существующие контракты и в тоже время имели возможность получить доступ к новому функционалу. Однако нет никаких стандартов описывающих универсальный подход практической реализации. Зачастую при разработке API мало задумываются о версионировании и если задумываются то не углубляются в варианты решения проблемы и выбирают первый вариант предложенный любимой поисковой системой. Данная стастья описывает возможные варианты которые могут быть использованы для реализации версионирования API. Рассматриваются существующие подходы их достоинства и недостатки. В данной статье речь идёт исключительно о API реализуемые поверх протокла HTTP и рассматривается реальный business case с обеспечением высокой доступности.
Реализация версионирования API должена удволетворять следующим требованиям:
Изолированность - выход новой версии API не должен затрагивать существующие версии. Скорость - определние к какой версии API хочет обратиться клиент должно быть максимально быстро. Наглядность - клиенту должно быть максимально легко и понятно к какой версии API он хочет обратиться.
Content Based
эта группа подходов основывается на определни версии API по средствам указания версии внутри HTTP пакета. Естественно что для определения куда же направить траффик необходимо задать правила например по средствам Regex шаблона. Следует отметить, что чем глубже находится информация о версии API тем больше времени и ресурсов необходимо серверу для определния цели.
URL path segment
HTTP GET: https://contoso.com/api/v1/foo
В данном подходе версия API к которой хочет обратиться клиент указывается как параметр в сегменте URL. Указание версии является обязательным. Это самый часто используемый подход. можно использовать с Tier 7 load balancers Microsoft Azure Application Gateway и Amazon Application Load Balancer. Также часто отмечают, что данный подход не сильно лоижться на RESTful по причине того, что URL должен прдеставлять иселючительно ресурс и не его версию.
URL query parameter
HTTP GET: https://contoso.com/api/foo?version=1
В данном подходе версия API к которой хочет обратиться клиент указывается как опциональный параметр в URL qurey. Указание версии является не обязательным и должно быть определенно какая версия API будет использована первая или последняя.
HTTP header
HTTP GET: http://contos.com/api Api-Version: 2
В данном подходе версия API к которой хочет обратиться клиент указывается как HTTP header. Указание версии является не обязательным и должно быть определенно какая версия API будет использована первая или последняя.
HTTP header
HTTP POST: http://contos.com/api Content { “Api-Version”: 2 }
Не работает для HTTP GET Данный подход используется в JSON-RPC подобных реализациях. Крайне дорого с вычислительной точки зрения.
Address Based
данный подход базируется на определнии целевого сервера на стадии DNS resolve.
HTTP GET: http://v1.api.contos.com/ или http://v1api.contos.com/
решение заключается в использовании префикса имени домена для указания версии API к которой хочет обратиться клиент.
Pros: Онсовным достоинством данного подхода является то, что процесс направления траффика переносится с инфратсруткруы на которой развернут API на DNS сревер и собственно не добавляет никакого overhead.
Можно использовать Tier 4 load balancers, соответсвенно может быть исопльзован не только для HTTP-based API a и TCP-based API.
Cons:
К минусам стоит отнести то, что для данного подхода потребуются манипуляции на DNS сервере.
В случае использования TLS придется покупать более дорогой wildcard ssl certificate.
Вывод
очевидно самым универсальным решением будет являться использование раздельных версий апи с Layer 4 Load Balancer и DNS based traffic management. Однако ваше решение может естественно отличаться ввиду определенных причин и ограничений.