<commit_before>---
layout: post
---

#Версионирование HTTP API 

В данной статье речь идёт исключительно о API реализуемые по верх протокла HTTP. 

Рассмотрим варианты и пути решения. 
Не секрет что активно используемые программные продукты должны развиваться для того что бы постянно удволтеворять нуждам клиентов. К сожалению не всегда можно построить API которая с самого начала будет достаточно гибка для того что бы поддреживать все возможные изменения сервиса и при этом не нарушать контракт с существующими клиентами. Логичным решением данной проблемы являетсе версионирование API. Однако нет никаких стандартов описывающих универсальный подход для версионирования. Следует отметить что зачастую при разработке API мало задумываются о версионировании и если и задумываются то не углубляются в варианты решения проблемы и выбирают первый вариант из поиска. 
Данная стастья нацеленна на  то чтобы дать представление о возможных стратегиях которые могут быть использованы для обеспечения версионности вашего HTTP API. Рассматривает существующие подходы их достоинства и недостатки. 
Процесс версионирования API должен удволетворять следующим требованиям: 

Для начала коротко опишем суть проблемы: дело в том что как гворил шекспир "Ничто не вечно под луной" и все меняется. Модель \ бизнес может имезниться однако не все способны быстро перейти на исопльзование новой версии и вам приходиться одновременно поддерживать несолкьо версий вашего ФPI. 

Давайте сразу обусловимся что мы рассматриваем реальный Business case с обеспечением высокой доступности. Используется load balancer. 

Задачи: 


Изолированность - выход новой версии API ни в коем случае не должен затрагивать существующие версии. 
Скорость - определние к какой версии API хочет обратиться клиент должно быть максимально быстро. 
Наглядность - клиенту должно быть максимально легко и понятно к какой версии API он хочет обратиться. 

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

Content Based - эта группа подходов основывается на определни версии API по средствам указания версии внутри HTTP пакета. Естественно что для определения куда же направить траффик необходимо задать правила например по средствам Regex шаблона. Следует отметить что чем дальше прячем тем больше времени и ресурсов необходимо серверу для определния цели. 

Для начала рассмотри проблему разработки. 

Один проет или разные разные проекты? 

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

Разнные проекты - легкость при разработки и возможная легкость при развертывании. 

Проблемы направления  

Варианты 

Content Based 

Url path segment  

HTTP GET: 

https://contoso.com/api/v1/foo 

Стоит отметить что этот вариант является наиболе распространеным. 

Основным недостатком является то что необходимо парсить TCP пакет. 

Так же часто отмечают что данный подход не сильно лоижться на RESTful по причине того что урл должен прдеставлять иселючительно ресурс и не его версию. 

Url query parameter 

HTTP GET: 

https://contoso.com/api/foo?version=1 

Header Get http://contos.com/api Api-Version: 2 

Content 
{ 
"Api-Version": 2 
} 


Не раюотает для HTTP GET 

Данный подход используется в JSON-RPC подобных реализациях. 

Крайне дорого с вычислительной точки зрения. 

Крайне сложно понять что куда потому что нужно распарсить все сообщение. 
Многие Tier 7 load balancers такие как Amazon / Azure и вовсе не поддерживают. 

Address Based - данный подход базируется на определнии целевого сервера на стадии DNS resolve.  

Address Based - решение заключается  в использовании префикса имени домена или он же называется сабдомен. 

Варианты 

http://v1.api.contos.com/ или http://v1api.contos.com/ 

Pros: 

Может быть исопльзовано не только для HTTP API 

Онсовным достоинством данного подхода является то, что процесс направления траффика переносится с инфратсруткруы на которой развернут API на DNS сревер и собственно не добавляет никакого overhead. 

Так же отлично можно использовать Tier 4 load balancers. 

Хоть данная статья и о HTTP API, следует отметить что данный подход можно использовать и с TCP based api. 

Cons: 

К минусам стоит отнести то, что для данного подхода потребуются манипуляции на DNS сервере. 

В случае использования TLS придется покупать более дорогой wildcard ssl certificate. 

Разница между подходами заключается в том что для того что бы направить траффик придется использовать Tier 7 Load Balancer - Балансироващик нагрузки который работает на уровне приложения. Т.е. для того что бы понять куда направлять траффик ему придется распарсить TCP сообщение как HTTP и по заданному шаблону определить соответсвующую версию API. 

При таком подоходе для направления траффика на нужную версиию можно использовать DNS based traffic management - распределения траффика на основании DNS. 

Вывод: очевидно самым универсальным решением будет являться использование раздельных версий апи с Layer 4 Load Balancer и DNS based traffic management. Однако ваше решение может естественно отличаться ввиду определенных причин и ограничений.

----
<commit_msg>Update 2016-09-21-HTTP-API-Versioning.md<commit_after>---
layout: post
---

#Версионирование HTTP API 

В данной статье речь идёт исключительно о API реализуемые по верх протокла HTTP. 

Рассмотрим варианты и пути решения. 
Не секрет что активно используемые программные продукты должны развиваться для того что бы постянно удволтеворять нуждам клиентов. К сожалению не всегда можно построить API которая с самого начала будет достаточно гибка для того что бы поддреживать все возможные изменения сервиса и при этом не нарушать контракт с существующими клиентами. Логичным решением данной проблемы являетсе версионирование API. Однако нет никаких стандартов описывающих универсальный подход для версионирования. Следует отметить что зачастую при разработке API мало задумываются о версионировании и если и задумываются то не углубляются в варианты решения проблемы и выбирают первый вариант из поиска. 
Данная стастья нацеленна на  то чтобы дать представление о возможных стратегиях которые могут быть использованы для обеспечения версионности вашего HTTP API. Рассматривает существующие подходы их достоинства и недостатки. 
Процесс версионирования API должен удволетворять следующим требованиям: 

Для начала коротко опишем суть проблемы: дело в том что как гворил шекспир "Ничто не вечно под луной" и все меняется. Модель \ бизнес может имезниться однако не все способны быстро перейти на исопльзование новой версии и вам приходиться одновременно поддерживать несолкьо версий вашего ФPI. 

Давайте сразу обусловимся что мы рассматриваем реальный Business case с обеспечением высокой доступности. Используется load balancer. 

Задачи: 


Изолированность - выход новой версии API ни в коем случае не должен затрагивать существующие версии. 
Скорость - определние к какой версии API хочет обратиться клиент должно быть максимально быстро. 
Наглядность - клиенту должно быть максимально легко и понятно к какой версии API он хочет обратиться. 

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

Content Based - эта группа подходов основывается на определни версии API по средствам указания версии внутри HTTP пакета. Естественно что для определения куда же направить траффик необходимо задать правила например по средствам Regex шаблона. Следует отметить что чем дальше прячем тем больше времени и ресурсов необходимо серверу для определния цели. 

Для начала рассмотри проблему разработки. 

Один проет или разные разные проекты? 

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

Разнные проекты - легкость при разработки и возможная легкость при развертывании. 

Проблемы направления  

Варианты 

Content Based 

Url path segment  

HTTP GET: 

https://contoso.com/api/v1/foo 

Стоит отметить что этот вариант является наиболе распространеным. 

Основным недостатком является то что необходимо парсить TCP пакет. 

Так же часто отмечают что данный подход не сильно лоижться на RESTful по причине того что урл должен прдеставлять иселючительно ресурс и не его версию. 

Url query parameter 

HTTP GET: 

https://contoso.com/api/foo?version=1 

Header Get http://contos.com/api Api-Version: 2 

Content 
{ 
"Api-Version": 2 
} 


Не раюотает для HTTP GET 

Данный подход используется в JSON-RPC подобных реализациях. 

Крайне дорого с вычислительной точки зрения. 

Крайне сложно понять что куда потому что нужно распарсить все сообщение. 
Многие Tier 7 load balancers такие как Amazon / Azure и вовсе не поддерживают. 

Address Based - данный подход базируется на определнии целевого сервера на стадии DNS resolve.  

Address Based - решение заключается  в использовании префикса имени домена или он же называется сабдомен. 

Варианты 

http://v1.api.contos.com/ или http://v1api.contos.com/ 

Pros: 

Может быть исопльзовано не только для HTTP API 

Онсовным достоинством данного подхода является то, что процесс направления траффика переносится с инфратсруткруы на которой развернут API на DNS сревер и собственно не добавляет никакого overhead. 

Так же отлично можно использовать Tier 4 load balancers. 

Хоть данная статья и о HTTP API, следует отметить что данный подход можно использовать и с TCP based api. 

Cons: 

К минусам стоит отнести то, что для данного подхода потребуются манипуляции на DNS сервере. 

В случае использования TLS придется покупать более дорогой wildcard ssl certificate. 

Разница между подходами заключается в том что для того что бы направить траффик придется использовать Tier 7 Load Balancer - Балансироващик нагрузки который работает на уровне приложения. Т.е. для того что бы понять куда направлять траффик ему придется распарсить TCP сообщение как HTTP и по заданному шаблону определить соответсвующую версию API. 

При таком подоходе для направления траффика на нужную версиию можно использовать DNS based traffic management - распределения траффика на основании DNS. 

Вывод: очевидно самым универсальным решением будет являться использование раздельных версий апи с Layer 4 Load Balancer и DNS based traffic management. Однако ваше решение может естественно отличаться ввиду определенных причин и ограничений.

----
{'fraction_non_alphanumeric': 0.024367731216540522, 'fraction_numerical': 0.0027690603655159685, 'mean_word_length': 4.754115772703133, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7045496', 'n_tokens_mistral': 4134, 'n_tokens_neox': 4865, 'n_words': 1437}