За окном 2023 год, а среди разработчиков только и разговоров, что про микросервисы да API First. Несмотря на то, что эти темы не новы, похоже, что их актуальность даже набирает обороты.
Про микросервисы уже много написано и теоретического и практического. Есть у этого подхода и свои евангелисты (Microservice Architecture) :) В целом это тема достаточно холиварная, особенно при крайних точках зрения. Сегодня мы ее отложим, но обязательно вернемся в контексте темы этой статьи. Конечно, это будет не менее обсуждаемая история, посвященная методологии API First и программным интерфейсам (прежде всего, web, но не только) при проектировании и разработке современных информационных систем :)
Меня зовут Антон, я руководитель Архитектурного комитета в компании SimbirSoft. Мы используем подход API First для проектов самой разной направленности, где есть несколько команд разработки (как минимум Backend и Frontend), а также при высокой неопределенности на этапе реализации (быстроменяющиеся требования и цели, параллельные процессы проектирования и реализации, высокие запросы к TTM и так далее).
Поскольку API First не является чем-то новым для многих команд разработки, то мы решили не писать про то, что все уже знают, а остановиться на отдельных вопросах и разобраться в практическом аспекте применения методологии API First в части проектирования, прототипирования и разработки.
Этот материал открывает цикл статей, посвященных практическому внедрению методологии API First в разработку наших команд. Если быть точным, то мы отдаем предпочтение «младшему брату» API First, практикующему проектирование (design), — известному как Design API First. Чтобы избежать путаницы, далее термин «API First» будет обозначать подход к разработке ПО, а термины «Design API First» и «Design First» – проектирование ПО в рамках подхода API First.
Статья будет полезна всем архитекторам и разработчикам, желающим внедрить подход API First на проекте.
Для начала ознакомимся с определением, рассмотрим предпосылки и основания для использования методологии, затем разберем поставленные цели и задачи. В заключении предоставим свои выводы, а также ошибки, проблемы и подводные камни, с которыми пришлось столкнуться.
Отметим, что основным ориентиром в проделанной работе для нашей команды стало именно проектирование API и возможность протестировать его результаты до написания кода. Вот другие важные проверенные моменты нашего практического исследования:
Сокращение затрат на разработку и времени выхода на рынок.
Параллельная разработка backend- и frontend-частей приложения.
Возможность внесения изменений в спецификацию после начала разработки (программирования).
Создание базовых (эталонных) спецификаций для типовых предметных областей.
Возможность создания SDK для базовых спецификаций на разных языках программирования.
Проектирование API архитектором и аналитиком, а не разработчиком с целью снижения уровня риска и частоты возникновения ошибок при непосредственной реализации (написании кода).
Современные стандарты разработки ПО предъявляют высокие требования, которые требуют соответствующей реакции, как со стороны отдельных команд разработки, так и ведущих компаний отечественного софтостроения.
Сегодняшние тренды обусловлены не столько модой на «микро» (микросервисы, микрофронтенды, микроапи), сколько развитием методологий разработки ПО, ростом команд, усложнением разрабатываемого ПО и повышением требований к нему.
В микросервисах как никогда актуален манифест реактивного программирования, а именно — его интерпретация: современное ПО должно сохранять отзывчивость и функциональность в условиях сбоев или программных ошибок, а также в моменты пиковых нагрузок на различные части системы. Таким образом, микросервисные архитектуры призваны решать проблемы вызова настоящего, обозначенные выше. Но, как известно, использование дополнительных уровней абстракции при проектирования и разработке ПО не проходит бесследно. Возникают издержки на поддержку этих уровней. Одним из побочных эффектов, требующим внимания, становится необходимость более частого и согласованного взаимодействия среди участников и команд, которые работают над разными частями (микросервисами) программного решения.
Будем считать, что предвестником подхода к решению этой проблемы был выпуск статьи Gartner: «Welcome to the API Economy». Статья послужила причиной появления такого подхода к проектированию ПО как API First.
API First – современная тенденция в методологиях разработки программных решений, популярность и необходимость которой обусловлена во многом, но не исключительно, успехом платформ и проектов, ориентированных на веб и массового онлайн-пользователя («Машина, платформа, толпа»). Будем считать, что API First – это методология разработки ПО, которая рассматривает API в качестве основания или конечного продукта, вокруг которого выстраиваются организационные процессы и сама разработка. При таком подходе ожидается, что поверх вашего API будут функционировать клиентские приложения (например, разработанные вами или сообществом SDK), а сам API будет «пульсом» вашего проекта. Пристальное внимание и большие нагрузки — вот некоторые из неизбежных трудностей, которые нужно постоянно учитывать при разработке проектов типа API First. Два из наиболее важных моментов, на которые мы обращаем внимание, — это согласованность и возможность повторного использования вашего API.
Иначе говоря, при разработке нужно предоставлять общедоступные контракты по взаимодействию с API, а также поддерживать обратную совместимость и непротиворечивость.
Непротиворечивость API — это:
Стандартизация. Использование стандартов и лучших практик, применяемых при проектировании и разработке API, применение собственного Guideline по написанию спецификаций;
Наименования. Использование продуманных названий полей и сущностей, точно описывающих концепции вашего продукта. Подробные описания методов, отсутствие аббревиатур и жаргона в описании;
Согласованность. Различные части вашего API используют интуитивно понятные и согласованные названия и сигнатуры вызовов.
Так как API First фокусируется на API как на первом и самом важном пользователе, то критически важной задачей становится формирование таких подходов, которые требуют определения контрактов (интерфейсов) на ранних этапах проектирования или разработки. Более подробно об этом можно почитать здесь.
На практике подход «API First» (например, при использовании стандарта OpenApi/Swagger) применяется в одном из двух представлений:
Design First.
Code First.
Второй пункт — это более традиционный подход к созданию API, при котором разработка кода происходит после того, как определены основные бизнес-требования, в конечном итоге из кода создается документация (Рис. 1).
Недостатки подхода Code First подробно описаны в статье Design API First:
Узкие места. Подход «сначала код» подразумевает каскадную модель разработки API, что приводит к возникновению узких мест. Команды специалистов, работающие над API, завершают каждую фазу в последовательном порядке, поэтому они не могут работать параллельно.
Бесполезные или раздутые API-интерфейсы. Когда вы пишете код, а затем получаете отзывы после нескольких версий закодированного API, в итоге часто получаются раздутые API-интерфейсы, в которых есть ненужные ресурсы. Вы также рискуете создать API, которые совершенно не помогут вашим клиентам.
Отсутствие документации. По окончании разработки над проектом создание документации может показаться гигантской рутинной работой. Поэтому она часто становится второстепенной задачей, а не приоритетом, и никогда не выполняется.
Потерянное время и деньги. Внесение изменений в уже закодированный API обходится гораздо дороже, чем в проект API. Вам, как правило, приходится прочесывать и писать много кода, чтобы исправить API после получения отзывов от пользователей. Если вы сначала написали код и не сделали документацию, можно в конечном итоге создать новые версии конечных точек и API, потому что никто в команде не помнит, как работает код.
Подход Design First предлагает сначала разработать контракт API, прежде чем писать какой-либо код. Сначала осуществляется проектирование, после чего его результаты могут быть преобразованы в человеко- и машиночитаемый контракт (API). Например, такой, как документ OpenAPI, из которого генерируется код (Рис. 2).
Подход в режиме Design API First имеет ряд преимуществ:
Команды backend и frontend могут осуществлять реализацию параллельно на основе сгенерированных интерфейсов API и использования средств мокирования (Prism, MockServer, Imposter).
Сокращается время на получение первой обратной связи по результатам реализации проекта. После того, как интерфейсы API готовы, их можно уже «пощупать» и получить общее понимание о том, как будет работать продукт.
Разработкой API занимаются более квалифицированные специалисты — архитекторы (возможно, с привлечением разработчиков), что позволяет повысить качество и делать это более унифицировано.
Получение более ранней обратной связи позволяет внести корректировки (как на уровне бизнес-логики, так и на уровне технической реализации) в структуру API на этапе проектирования, что позволяет убрать из полного цикла (проектирование – реализация – тестирование – внесение изменений) самый трудоемкий этап реализации.
Наличие формализованного описания структуры API в виде YAML или другой JSON, что позволяет использовать инструменты автоматической генерации интерфейсов API, исключая ошибки разработчиков и убирая рассогласование между этапом проектирования и реализации.
Использование формализованных описаний API повышает процент повторного применения таких решений, которые могут рассматриваться как отдельные модули, реализуемые в других проектах (примеры таких решений вы найдете в нашей следующей статье «Пример реализации Design API First на примере реализации сервиса аутентификации»).
Автоматическая генерация документации, которая всегда остается в актуальном состоянии и не требует ручной корректировки при внесении изменений, например с помощью PlantUML.
Возможность применять автоматизацию для более быстрой обработки изменений, как на стороне backend, так и на стороне frontend (об особенностях использования автоматической генерации моделей в приложениях на JS-фреймворках расскажем в другой нашей статье «Генерация моделей на основе спецификации на стороне frontend-приложений»).
Конечно, реальный процесс использования подхода Design API First представляет собой более сложный технический процесс. Однако дополнительные затраты, которые приходится нести на этапе проектирования, с лихвой окупаются на последующих этапах реализации. Получение более полного и формализованного представления о системе на этапе аналитики играет очень важную роль в понимании ее последующего функционирования и дает всем участникам процесса (как заказчику, так и команде разработчиков) возможность как можно раньше увидеть риски, проблемы и принять согласованные решения об их устранениях. О том, какие средства и инструменты мы используем в компании SimbirSoft, расскажем в нашей следующей статье, которая посвящена вопросам интеграции паттерна Design API First в наш конвейер разработки программного обеспечения.
Спасибо за внимание!
Другие полезные материалы для разработчиков и архитекторов в IT публикуем в наших соцсетях — ВК и Telegram.