iconПузатый Сад

С утра API — вечером Код

Created:
Modified:
Size: 14 min read

Info

Не прошло и двух лет, но я всё-таки сделал это! Эта статья — расшифровка моего доклада о подходе API First на Backend Day в Нижнем Новгороде в 2023 году. Презентация доступна по ссылке и продублирована в конце статьи.

Проблемы и истории

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

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

  1. Аналитики часто описывают контракты в виде таблиц, где собраны параметры, дефолтные значения, примеры, типы и так далее. Это таблица, которая показывает, как должен выглядеть JSON, который вы пересылаете по сети между сервисами.
  2. Примеры в виде JSON. В них собраны те же поля, примеры значений, а также встраиваются комментарии. В итоге этот JSON может стать не совсем валидным.
  3. Контракт может быть описан просто каким-то текстом. Например, “Нам надо добавить ФИО сотрудника и день его рождения”. Это такая неформальная спецификация без именования полей и какой-либо структуры. Вся ответственность за понимание контракта ложится на разработчика.
  4. Есть контракты, описанные в виде дизайна. Это набор блоков, который отражает данные, которые необходимо передавать через API.
  5. Ну и, конечно, вариант, о котором я больше буду говорить в этом докладе, — это формальная спецификация. OpenAPI или какие-то альтернативные варианты.

Всё это добро можно хранить в совершенно разных системах.

В своей практике я видел, как различные описания складывали в Figma. Очень популярный вариант — использовать Google Docs или вики для фиксации требований и контрактов для API. Также часто информация записывается в трекер задач, например, в Jira. Но вариант, который приветствуется и пропагандируется в этом докладе, — это использование API Registry на основе готовых продуктов или репозиториев со спецификациями.

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

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

Еще один пример. Вам предоставляют OpenAPI спецификацию, в которую очень хочется верить. Однако в ней определен вот такой объект LocalTime. Это настораживает? И правильно, потому что на самом деле в виде даты ожидается строка в ISO формате. Еще хуже бывает, когда регистр первых букв полей в спецификации отличается от реального.

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

Примеров таких множество. На мой взгляд, их можно избежать, используя подход API First.

Немного о себе

Проблематика обозначена, теперь расскажу немного о себе. Меня зовут Илья Зонов, и я архитектор. С 2020 года работаю в Тинькофф, где начинал как архитектор в кредитах для среднего и малого бизнеса. Сейчас, в 2023 году, занимаюсь запуском Т-Лизинга. В соцсетях меня можно найти под никами izonov или puzan. На слайде обратите внимание на фото с моим псом, который, конечно же, помогает мне каждый день принимать сложные архитектурные решения и иногда заменяет мне уточку.

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

API First

Что же такое API First? Это подход, который продвигает идею проектирования API до написания какого-либо кода. Мы сначала сосредотачиваемся на том, как будет выглядеть API, будь то Rest API через HTTP или асинхронный API через Kafka или RabbitMQ. Внедрение этого процесса могут осуществляться по-разному. Сегодня я хочу сосредоточиться на том, какие преимущества это приносит.

  1. Во-первых, это Просто. С помощью генераторов мы можем избежать написания однотипного кода для моделей и контроллеров. Современные инструменты на рынке позволяют сосредоточиться на сложном коде для бизнес-логики, не отвлекаясь на рутину.
  2. Во-вторых, API First — это Быстро. Появляется возможность начать разработку в двух командах одновременно. Благодаря проектированию API на ранних этапах жизненного цикла разработки мы получаем быструю обратную связь о его пригодности и избегаем переписывания API на поздних стадиях. Это фактически является частью практики Shift Left, которая перемещает такие процессы, как тестирование и проверка безопасности, в начало разработки для снижения рисков перед выпуском продукта.
  3. В-третьих, API First очень полезен для бизнеса. Бизнес рассматривает IT как инструмент, а еще чаще как Lego, из которого можно собрать новый продукт. API First в данном случае позволяет приблизить IT к аналогии с Lego, а также зафиксировать общий язык для бизнеса и IT, который автоматически попадет в код.

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

Быстро

Перейдём к аспекту скорости, которую обеспечивает API First. Рассмотрим это в сравнении с подходом Code First. Последний предполагает, что код является основным источником истины, и именно с него начинается работа. Я бы назвал это подходом “возникающего API”. Часто только после запуска приложения мы можем точно увидеть, как выглядит API.

  • Из описания вытекает главный плюс подхода Code First: это скорость первого запуска в production. Фактически, это позволяет быстро развернуть прототипы.
  • Также отсутствует необходимость изучать дополнительные инструменты и новые форматы спецификаций. Достаточно использовать проверенные инструменты, такие как Java/Kotlin, Python, C# — больше ничего не требуется. Это экономит время.
  • Code First отлично подходит для небольших изолированных команд с минимальной внешней коммуникацией.

Что же предлагает API First в плане скорости?

  • Возможность получить раннюю обратную связь о жизнеспособности API от всех участников проекта благодаря ревью спецификации.
  • Формирование Ubiquitous Language продукта на основе API. Терминология автоматически попадает в код, что экономит время и устраняет недопонимания при взаимодействии с бизнесом.
  • Возможность параллельной разработки. Нет необходимости ждать, пока будет написан код.
  • Генераторы помогают автоматизировать создание однотипного кода.
  • API, над которым тщательно поработали, проще и приятнее интегрировать разработчикам. Советую при проектировании представить, что вам самим нужно будет интегрировать созданный API.

Посмотрим, как выглядит процесс разработки с каждым методом. Начнем с Code First.

  • Сначала у нас есть идея в виде задачи в голове у бизнесмена в шляпе.
  • Затем появляется рыжеволосая разработчица, которая самостоятельно придумывает API.
  • Код проходит через стадию сборки. На этом или следующем этапе генерируется документация для API. Стоит задуматься, как это происходит. Мы просим некий инструмент описать, что же в итоге получилось. Это напоминает, как в современном мире ChatGPT помогает объяснить, что делает код.
  • Далее, видимо лысый тестировщик пытается понять, соответствует ли реализованный API поставленной задаче. Очень вероятно, что на этом этапе даже на уровне API потребуется консультация с разработчицей и бизнесом. Также высока вероятность отправить задачу на доработку.

Что предлагает API First?

Шагов становится больше. Главное отличие — добавление этапа проектирования и ревью API. Этот шаг призван собрать команду из представителей бизнеса, разработки и тестирования. Он исключает из цикла обратной связи написание кода, связанного с возвратом API на доработку. Это напоминает подход 3-амиго.

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

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

Пара слов о Shift Left. Представьте график, где по оси Y отображается качество, измеряемое количеством багов, а по оси X — этапы разработки. В традиционной модели разработки большинство багов выявляется на поздних стадиях, таких как тестирование или даже в продакшене. Модель Shift Left предлагает перенести практики, такие как тестирование и аудит безопасности, на более ранние стадии. Это позволяет получать обратную связь на начальных этапах разработки. Таким образом, подход API First способствует выявлению проблем на более ранних этапах.

Просто

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

Для спецификаций HTTP контрактов наиболее популярны такие решения, как gRPC, OpenAPI и GraphQL. В детали сейчас вдаваться не буду, но для всех этих инструментов существуют генераторы, линтеры и мок-серверы, которые помогут вам сэкономить время. Генераторы основаны на движках шаблонов: не забывайте, что шаблоны всегда можно подкорректировать под свои нужды.

Для асинхронного взаимодействия также существует аналог OpenAPI под названием AsyncAPI. Он призван охватить все сценарии реализации API для event-driven решений. Из популярных решений для описания форматов также стоит отметить Avro, JsonSchema и Protobuf.

Желтым выделены решения, которые активно используются в Tinkoff.

Дополнительно хочется упомянуть проект JSight. Это попытка создать спецификацию для HTTP интерфейсов, которая будет менее многословной по сравнению с OpenAPI. Если кто работал с Avro, то это напоминает представление Avro IDL, которое заметно компактнее и читаемее представления схемы в виде JSON.

Заметка из 2025-го года

В текущем проекте мы активно используем Typespec, который также позволяет компактно фиксировать контракты. Его можно применять для генерации OpenAPI спецификаций, что значительно облегчает работу, избавляя от необходимости погружаться в многострочные YAML-файлы.

Интересны также инструменты, которые помогают отслеживать изменения, вносимые в API. Примеры, которые я использовал, представлены на слайде.

  • Apicurio — набор решений от Red Hat для проектирования API, построенный на основе OpenAPI и AsyncAPI. Одно из приложений — это реестр, через который можно контролировать уровень совместимости API между версиями.
  • OpenAPI Diff — позволяет сравнивать версии спецификаций и выявлять обратно несовместимые изменения. Сейчас я как раз работаю над репозиторием, который проверяет изменения спецификаций с помощью этого инструмента.
  • Kafka Schema Registry — решение от Confluent, тесно интегрированное с Kafka. Оно также позволяет указать, какой уровень совместимости требуется: backward, forward или оба одновременно.

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

Несколько примеров API First в Тинькофф:

  • Внутри компании у нас есть собственная дев-платформа с сервис-каталогом. Формально можно добавить туда свои контракты в формате OpenAPI и поделиться ими между командами. Эта часть проекта находится на начальной стадии развития.
  • Существует крупный агрегатор различных OpenAPI спецификаций: TWork Swagger Proxy. С его помощью можно найти нужный метод или спецификацию.
  • В открытом доступе в OpenSource представлен JVM-based фреймворк Kora. Этот продукт активно продвигает использование шаблонов для генерации контроллеров по OpenAPI спецификациям. Шаблон доступен прямо в коде проекта. Проект относительно молодой, но в Tinkoff уже более половины генерируемого Java кода по спецификациям создается в проектах на основе Kora.
  • Также есть крупный проект под названием Streaming Data Platform. Это основа для будущей реализации Data Mesh подхода в Tinkoff. Каждый проект, который хочет поставлять данные в DWH для аналитики, описывает свои данные в виде Avro схем. Это очень тщательно ревьюится, создавая точку коллаборации между разработкой и бизнес-аналитикой. Затем данные отправляются через Kafka и автоматически распределяются в нужные таблицы.

Полезно бизнесу

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

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

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

Далее зона ответственности расширяется ещё больше. Мы начинаем смотреть на продукт в целом, и становится сложно углубляться в детали каждого модуля или приложения. На первый план выходят стрелочки, которые обозначают API на этой схеме. Архитектор и бизнес обычно видят именно такую картину, где каждый квадратик — это отдельный домен: продажи, уведомления, расчётно-кассовое обслуживание и так далее, которые вместе формируют готовый продукт. А соединяющим звеном между ними выступает API.

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

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

Одна из самых известных историй о том, как бизнес обратил внимание на API, — это Amazon API Mandate, сформулированный Джеффом Безосом около 2002 года. До нас этот мандат дошел через размышления бывшего сотрудника Amazon о платформах. Интересно, что помимо пяти основных постулатов, в этом обсуждении упоминался и шестой: тот, кто не соблюдает описанные правила, будет уволен. Основные идеи мандата таковы:

  • Взаимодействие между командами должно осуществляться через API.
  • Реализация вторична.
  • Должна быть возможность опубликовать любое API для внешнего клиента. Это формирует культуру равнозначности между внешними и внутренними клиентами.

Зачем бизнесу API? На мой взгляд, всё дело в том, что компании стремятся быстро создавать продукты из готовых блоков. Отсюда и возникает идея IT как Lego. Однако даже в современном мире интеграция различных решений часто напоминает имплантацию органов, как говорил Джон Д. Кук в своём блоге. API First, сосредотачиваясь на проектировании API, улучшает возможности соединения между этими блоками.

Ещё одна история из 2012 года — 12 факторов от компании Heroku, которые описывают, каким должно быть приложение для быстрого и эффективного запуска в облачной инфраструктуре. Подробно об оригинальных факторах можно почитать по ссылке. Интересно, что уже в 2016 году Кевин Хоффман в своей небольшой книге добавил ещё 3 фактора.

На мой взгляд, справедливо были добавлены пункты, связанные с безопасностью (о которой ничего не говорилось в оригинальных факторах), а также телеметрией (которая является неотъемлемой частью наблюдаемости распределённых приложений). И, конечно, API First, который попал в список во многом благодаря распространению микросервисной архитектуры и облаков.

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

Кроме того, на рынке есть компании, которые строят свой бизнес вокруг решений для создания API. Например, Smartbear и Postman.

Первая, похоже, скупила все компании, которые занимались инструментами для OpenAPI. Например, их последняя покупка — компания Stoplight, которая разрабатывала альтернативный редактор для OpenAPI спецификаций и линтер. Также под брендом компании доступны такие инструменты, как Cucumber (для фиксации поведения системы в виде BDD тестов и сценариев), Pact (для контрактного тестирования), Swagger Hub и другие.

На главной странице сайта Postman вы быстро найдете упоминания про API First и даже отдельную книгу, полностью посвященную этой теме.

Подытожим блок про бизнес. Бизнес видит IT как Lego, а значит, мы (разработчики, архитекторы) должны предоставить надежный, качественный клей между кубиками. И делаем это через API, который может быть хранилищем общего языка с бизнесом.

Итоги

Конечно, существуют барьеры, которые необходимо преодолеть.

  1. Шаблоны и генераторы. С ними нужно научиться работать. Например, в OpenAPI формально можно использовать oneOf, но мало шаблонов поддерживают эту функцию. Стоит разобраться с шаблонами, написанными на Mustache. Я рекомендую глубже вникать в эти инструменты, уметь вносить изменения и адаптировать их под свои нужды. Это поможет внедрить необходимую логику в ваши сервисные интерфейсы или клиенты. Например, в кредитах и лизинге мы интегрировали через генераторы часть логирования внешних запросов и настройку метрик.
  2. Может быть сложно перестроить процесс разработки. Однако, если вы уже используете практику 3-амиго, то этап проектирования API можно встроить в этот процесс, что значительно упростит задачу.
  3. Спецификации могут ограничивать ваши возможности. Некоторые решения, такие как gRPC и Avro, надо просто принять.

Давайте подведем итоги и рассмотрим ключевые идеи, лежащие в основе API First:

  • Во-первых, переносим проектирование API на ранние этапы разработки, реализуя тем самым Shift Left с ранней обратной связью.
  • Во-вторых, рассматриваем API как центральный элемент системы и относимся к нему соответствующим образом. Это источник истины и хранитель общего языка с бизнесом.
  • В-третьих, API Governance обеспечивает контроль и безопасные изменения.

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

Хочу выразить огромную благодарность моему коллеге и другу Вове Чистякову за то, что он придумал название для этого доклада. Был еще более взрывной вариант: “До свадьбы ни-ни, до кода API”, но его не одобрили :) Также огромное спасибо моей жене, которая терпеливо множество раз слушала мои рассказы про API First дома.

Спасибо!!!

Презентация

Graph View