Русский
Русский
English
Статистика
Реклама

Версионирование

Делаем новую версию API. Быстро и легко

09.04.2021 14:13:02 | Автор: admin

Коммуникация правит миром. Взаимодействие необходимо и между людьми, и между программным обеспечением. Хотите адекватного ответа на ваш запрос к приложению? API вам в помощь! Необходимость в реализации API возникает практически во всех проектах, и со временем мы задумываемся, можно ли улучшить текущий API? Последовательность конкретных шагов и реальные примеры наш рецепт создания рабочего API-проекта.

Первый вопрос, который нужно задать: А точно ли стоит реализовать новую версию API? Возможно, уже работающая версия отвечает всем необходимым вам критериям. Но если вы уже для себя ответили да на поставленный вопрос, то читайте дальше и найдете наш ответ. Если вы ответили нет, то тоже читайте дальше и применяйте наш опыт проектирования и реализации в следующих ваших проектах.

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

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

Рассмотрим на примере API для работы с котиками то, как мы совершенствовали один из наших проектов.

Как понять, что стоит реализовать новую версию API

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

  • определить уровень зрелости API;

  • проверить, есть ли у API версионность;

  • проверить наличие документации API.

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

Определим уровень зрелости API

Для этого идеально подходит модель Леонарда Ричардсона, в которой он выделяет четыре уровня зрелости API:

  • Уровень 0: Один URI и один HTTP метод (в основном метод POST);

  • Уровень 1: Несколько URI и один HTTP метод;

  • Уровень 2: Несколько URI, каждыи из которых поддерживает разные HTTP методы;

  • Уровень 3: HATEOAS. Ресурсы сами описывают свои возможности и взаимосвязи.

Если API соответствует 0 или 1 уровню зрелости, то определенно есть куда расти, потому что:

  • Если используется один URI, то не понятно с каким ресурсом работаем;

  • Не понятно, что делаем с ресурсом, так как используется один HTTP метод;

  • Использование одного URI создает трудности с документацией API;

  • Использование одного URI создает трудности с логированием входящих запросов;

  • Из-за использования одного URI, информация о типе ресурса передается в теле запроса.

Посчитаем, сколько если у нас получилось, и определим направление разработки. Это поможет сконцентрироваться на задачах и четко сформулировать дальнейшие шаги.

Проверим, есть ли у API версионность

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

Благодаря версионности можно также ранжировать документацию по версиям, чтобы разработчики клиента всегда могли определить, насколько у них актуальная документация. Согласитесь, это удобно разработчикам, тестировщикам и сотрудникам технической поддержки.

Рассмотрим 3 основных способа версионирования API и разберем подробнее каждый из них. Современные разработчики выделяют следующие способы:

- Использование разных URI (Uniform Resource Identifier);

- Использование параметра запроса;

- Использование заголовка, Accept Header/Media Type.

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

  1. Использование разных URI простой в проектировании, реализации и документировании способ версионирования. Однако он имеет целый ряд недостатков:

  • приводит к загрязнению URI, так как префиксы и суффиксы добавляются к основным строкам URI;

  • разбивает существующие URI, то есть все клиенты должны обновиться до нового;

  • приводит к увеличению размер HTTP кэша для хранения нескольких версии;

  • создает большое количество дубликатов URI, может снизить производительность приложения из-за увеличения количества обращении к кэшу;

  • является крайне негибким и не позволяет просто изменить ресурс или небольшой их набор.

Пример:

GET v1/cats/{name}

2.Использование параметра запроса позволяет легко документировать версионность и рекомендуется к использованию в случае, если важно HTTP кэширование. Однако и этот способ приводит к загрязнению пространства URI.

Пример:

GET cats/{name}?version=v1

3. Использование заголовка и Accept Header/Media Type также легко документировать и, в отличие от предыдущих способов не приводит к загрязнению пространства URI. Но и у этого способа выделяют несколько минусов:

-приводит к неправильному использованию заголовков, так как они изначально предусматривались не для версионирования;

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

Пример:

GET cats/{name}

Headers: version=v1

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

Проверим наличие документации API

Даже к фену удобно иметь описание, не говоря уже о серьезной проекте разработки ПО. Поэтому наглядное описание API всегда удобно для использования как backend, так и frontend разработчиками. Документация может быть реализована, например, с помощью Swagger (фреймворк для спецификации RESTful API), он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы с помощью Swagger UI:

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

  • соответствует 0 уровню зрелости (Один URI и один HTTP метод);

  • невозможно достоверно установить, с каким ресурсом API работает и какие функции выполняет;

  • отсутствуют автоматизированные средства документации API, что приводит к неполной документации API или ее полному отсутствию для некоторых запросов;

  • появляются сложности с поддержкой обратной совместимости, так как нет версионности API.

Для большего понимания того, что не нравилось, приведем пример того, как выглядел наш API.

Пример:

POST /cats - должен вернуть котика по имени Пушок (гарантируется, что у

requestBody: { котиков уникальные имена);

"name": "Pushok"

}

POST /cats - должен вернуть вернуть список белых котиков;

requestBody: {

"color": "white"

}

Цели реализации нового API

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

  • Ускорение процесса клиентской и серверной разработки;

  • Снижение временных затрат на поддержку и развитие API;

  • Добавление автогенерации документации API;

  • Поддержка версионности API для упрощения поддержки обратной совместимости с помощью версионности API.

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

Повышаем уровень зрелости API

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

Для того, чтобы повысить API с 0 на 2 уровень зрелости были проанализированы все текущие проблемы и выделены следующие пункты:

1.Разделение текущего API на смысловые части для выделения соответствующего ресурса для каждой части;

2.Использование методов, соответствующих действиям над ресурсами: GET, POST, PUT, DELETE;

3.Обозначение ресурса во множественном числе;

Пример:

GET /cats - должен вернуть список котиков

GET /cats/Pushok - должен вернуть котика по имени Пушок

(гарантируется, что у котиков уникальные имена)

4. Указание фильтрации в параметрах.

Пример:

GET /cats?color=white - должен вернуть список белых котиков

Добавляем версионность

После повышения зрелости API выходим на новый этап и выбираем способ версионирования. Для текущего проекта был выбран способ версионирования с использованием собственного заголовка. Это решение не попадает в пункт неправильное использование заголовков, так как будет использоваться собственный заголовок. Для удобства было решено указывать версии вида 2.n.

Для начала реализуем контроллер:

После этого для реализации версионности, создадим enum:

Далее создадим конвертер, используя внутренний Spring Framework интерфейс Converter<S,T>. Он преобразует исходный объект типа S в целевой типа T, в нашем случае преобразует текстовое значение версии в тип Enum ApiVersion до попадания в контроллер:

Если в заголовке было отправлено значение 2.0, до контроллера оно дойдет уже в виде v2. При такой реализации вместо того, чтобы перечислять все доступные версии, можно будет указать в заголовке, что ожидается enum. А контроллер после добавления версионирования будет выглядеть так:

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

Указание версии было решено сделать обязательным.

Документируем

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

Рассмотрим пример реализации документации для созданного выше контроллера. Для этого реализуем интерфейс:

С его помощью можно добавить название и описание API текущего контроллера, описание каждого запроса, плюс есть возможность указать схему тела запроса. Остальную информацию Swagger получает из аннотаций контроллера.

Перейдя в Swagger UI увидим задокументированное API:

Получим более подробную информацию:

Преимущества новой версии API

На примерах выше был продемонстрирован переход с 0 уровня зрелости API на 2 уровень зрелости согласно модели Ричардсона, благодаря этому мы получили:

  • повышение уровня зрелости API, что дало понимание, с каким ресурсом мы работаем и что с ним делаем;

  • версионирование, которое позволит вносить изменения в текущий API;

  • удобное документирование и появление внятной документации, да и документации вообще.

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

Скорость разработки при переходе на новую версию API значительно возросла, ведь разработчикам стало значительно удобнее и приятнее работать. Наш путь разработки оказался вполне рабочим и его смело можно рекомендовать для применения в реальных проектах. А может в вашем арсенале есть другие варианты? Готовы обсудить!

Подробнее..

От монолита к микросервисам ускорили банковские релизы в 15 раз

24.07.2020 12:09:40 | Автор: admin
Бывает, что компания использует устаревшую монолитную IT-систему, с которой сложно быстро выпускать обновления и решать свои бизнес-задачи. Как правило, рано или поздно владелец продукта начинает проектировать новое, более гибкое архитектурное решение.

Недавно мы писали о том, как работают IT-архитекторы, а теперь расскажем подробности об одном из наших кейсов и покажем схему работы системы. В этом проекте мы помогли заменить коробочное банковское приложение на микросервисное ДБО, при этом наладив быстрый выпуск релизов в среднем 1 раз в неделю.



Примечание: в нашем примере мы хотим показать, в чем монолитные приложения могут уступать микросервисным, особенно в финтех-решениях. В силу NDA мы можем делиться не всеми техническими подробностями проекта однако, мы надеемся, что наш кейс может быть полезен тем, кто работает с онлайн-банками.

Проблемы коробочного монолита


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

Именно такую коробочную систему дистанционного банковского обслуживания (ДБО) использовал один из наших клиентов. Онлайн-банк представлял собой монолитное приложение с достаточно небольшим набором функций.

Для того, чтобы не уступать конкурентам, банку нужно было постоянно внедрять улучшения и новые фичи. Однако, даже для того, чтобы просто передвинуть кнопки в приложении, приходилось обращаться к вендору. Обновления выходили в среднем 1 раз в квартал.

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

  1. Вендор вносил желаемые изменения неприемлемо долго, а переписать мобильный интерфейс в конкретной коробке и вовсе было практически невозможно.
  2. Из-за сбоев в шине данных или коробке пользователи зачастую не могли войти в онлайн-банк.
  3. Работать с приложением пользователи могли только в том случае, если у них была установлена самая свежая версия.
  4. Для распределения нагрузки инстансы монолита были развернуты на нескольких серверах, каждый из которых обслуживал свою группу абонентов. При падении одного из серверов пропадал доступ у всех абонентов соответствующей группы.
  5. Вся экспертиза хранилась у производителя коробочного решения, а не в банке.
  6. Из-за того, что банк не мог оперативно внести изменения по просьбам пользователей, а функциональность была недостаточной по сравнению с конкурентами, появился риск оттока клиентов.

В результате банк принял решение постепенно отказаться от коробки и разработать собственное ДБО, с микросервисной архитектурой, чтобы ускорить разработку функций и обеспечить удобство и безопасность для пользователей.

С чего мы начинали


Создание онлайн-банка началось с проектирования верхнеуровневой архитектуры, найма разработчиков в штат и подключения нашей выделенной команды. При этом архитектуру нужно было заложить с запасом прочности, в расчете на будущее расширение.

На старте наша команда Backend-разработчиков занималась реализацией отдельных базовых функций: например, денежными переводами. Однако, у нас был достаточно большой опыт работы с онлайн-банками, один из наших проектов к этому моменту вошел в отраслевой рейтинг Markswebb, поэтому мы предложили банку помощь в проектировании архитектуры и получили зеленый свет.

Архитектура

Вместе с владельцем продукта мы приняли решение использовать Spring Cloud, который предоставляет все необходимые функции для реализации микросервисной архитектуры: это и Service discovery Eureka, Api Gateway Zuul, Config server и многое другое. В качестве системы контейнеров для Docker-образов выбрали OpenShift, потому что инфраструктура банка была заточена под этот инструмент.

Также мы проанализировали, какие особенности старой коробки могут осложнять работу пользователей. Один из основных недостатков заключался в том, что система синхронно работала через шину данных, и каждое действие пользователей вызывало обращение к шине. Из-за больших нагрузок часто происходил отказ шины, при этом переставало работать все приложение. Кроме того, как и во многих старых банковских продуктах, накопилось легаси наследство в виде старого и тяжеловесного CORE АБС, переписывать которое было бы сложно и дорого.

Мы предложили ряд улучшений:

  • Версионирование

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

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

  • Асинхронность

Мы реализовали библиотеку, которую можно использовать в сервисах, где требуется асинхронная работа. Библиотека реализует выполнение асинхронных задач, подходит для использования на любом количестве копий сервисов, и они не мешают друг другу. Синхронизация между различными копиями производится с помощью очереди сообщений Kafka.

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

  • Кэширование

Чтобы ускорить работу приложения и снизить нагрузку на внутренние банковские ресурсы, организовано кэширование данных с помощью Reddis. В качестве кэша служит KeyDB, который показывает хорошие результаты и совместим со многими системами, использующими Reddis. Данные кэшируются не после запроса пользователя, а при изменении пользовательских данных, что позволяет иметь к ним доступ независимо от внутренних банковских систем.

Что изменилось в системе


Как было отмечено выше, в старом онлайн-банке backend был выполнен в монолитной архитектуре, приложение разворачивалось на отдельной машине. При увеличении нагрузки приходилось разворачивать новые сервера. При падении сервера у некоторых пользователей полностью не работало мобильное приложение.





В новом решении использована микросервисная архитектура, что позволяет разворачивать столько копий сервисов, сколько требуется для того или иного функционала. Мы добавили кэширование данных на основе KeyDB, чтобы не только увеличить скорость получения информации, но и снизить нагрузку на базу данных.



Давайте рассмотрим пример получения данных по счетам пользователя в новой архитектуре. Запрос пользователя из мобильного приложения попадает через балансировщик на Gateway, который понимает, на какой из сервисов направить запрос. Далее попадаем на API сервис счетов. Сервис сперва проверяет, есть ли актуальные данные пользователя в Cache. При успешном исходе возвращает данные, в ином случае отправляет запрос в Middle сервис счетов.

Обновление данных в сервисе может происходить в различных случаях. Например, при непосредственном запросе от пользователя сервис создает задачу на обновление данных, которая выполняется асинхронно, и полученные из ESB данные обновляются. Также сервис получает сообщения из очереди сообщений и реагирует на них. Например, сервис получает сообщение о входе пользователя в приложение и сразу же обновляет данные по счетам, получает данные об операциях со счетом от других сервисов и обновляет у себя данные. Таким образом, пользователь всегда видит актуальные данные по своим счетам.

Среди наиболее важных изменений можно отметить следующие:

  • Гибкость масштабирования

Для увеличения отказоустойчивости системы сервисы распределены по разным серверам. Это позволяет сохранять систему в работоспособном состоянии в случае падения одного из них. Для своевременного реагирования на нестандартные ситуации мы внедрили систему мониторинга, это помогло при необходимости вовремя масштабировать сервисы. Подключили DevOps для настройки с нуля CI/CD на серверах клиента, выстроили процессы развертывания и поддержки будущего приложения на нескольких серверах.

  • Ускорение релизов за счет версионирования

Ранее при обновлении мобильной версии одни пользователи уже применяли новую версию, а другие нет, но число последних было минимально. При разработке нового ДБО мы реализовали версионирование и возможность выпускать релизы без риска, что приложение перестанет работать у большой части клиентов. Сейчас при реализации отдельных функциональностей в новых версиях мы не ломаем старые версии, а значит, нет необходимости проводить регресс. Это помогло ускорить частоту релизов минимум в 15 раз теперь релизы выходят в среднем 1 раз в неделю. Команды Backend и Mobile могут одновременно и независимо работать над новыми функциональностями.

Подводя итоги


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

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

Архитектура приложения заложена с учетом дальнейшего роста продукта и инструментов разработки, которые использует банковская инхаус-команда, чтобы владелец продукта мог самостоятельно вносить любые доработки в ДБО. Сроки активной разработки альфа-версии составили около года, еще через 3 месяца вышла бета-версия для всех пользователей.
Надеемся, что описанная схема работы может быть полезна при создании других финтех-продуктов.

Спасибо за внимание!
Подробнее..

Категории

Последние комментарии

  • Имя: Макс
    24.08.2022 | 11:28
    Я разраб в IT компании, работаю на арбитражную команду. Мы работаем с приламы и сайтами, при работе замечаются постоянные баны и лаги. Пацаны посоветовали сервис по анализу исходного кода,https://app Подробнее..
  • Имя: 9055410337
    20.08.2022 | 17:41
    поможем пишите в телеграм Подробнее..
  • Имя: sabbat
    17.08.2022 | 20:42
    Охренеть.. это просто шикарная статья, феноменально круто. Большое спасибо за разбор! Надеюсь как-нибудь с тобой связаться для обсуждений чего-либо) Подробнее..
  • Имя: Мария
    09.08.2022 | 14:44
    Добрый день. Если обладаете такой информацией, то подскажите, пожалуйста, где можно найти много-много материала по Yggdrasil и его уязвимостях для написания диплома? Благодарю. Подробнее..
© 2006-2024, personeltest.ru