5 неочевидных вещей об API, которые стоит учитывать при проектировании продукта

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

Содержание

API (от англ. Application Programming Interface — интерфейс программирования приложений) существует десятилетиями, но его роль в разработке продолжает меняться. По данным международного исследования, в котором участвовали более 5700 разработчиков, архитекторов и руководителей, 82% организаций уже в той или иной степени используют API-first-подход, а четверть называют себя полностью API-first.

При этом API становится не только техническим, но и экономическим активом. 65% опрошенных организаций получают доход от своих API-программ. Среди них 74% связывают с API не менее 10% совокупной выручки.

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

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

Представим сервис расчёта стоимости доставки. Другие компоненты передают ему параметры заказа и получают стоимость. Внутри компания может изменить алгоритм расчёта, источник данных или структуру самого сервиса. Если контракт API сохранён, подключённым системам необязательно знать об этих изменениях.

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

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

Масштаб использования API делает этот вопрос уже не только техническим. По данным исследований, 65% опрошенных организаций сообщили, что получают выручку от своих API-программ. Среди организаций, которые монетизируют API, 74% связывают с ними не менее 10% совокупной выручки. Ещё 42% респондентов среди эффектов использования API отметили сокращение инженерных затрат за счёт уменьшения объёма дублирующей работы.

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

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

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

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

Практики управления такими изменениями при этом распространены неравномерно. Согласно опросам, 60% опрошенных версионируют свои API, тогда как контрактное тестирование используют только 17%. Для сравнения: функциональное и интеграционное тестирование применяют по 67% респондентов.

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

Само наличие API ещё не означает, что архитектура стала модульной.

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

Поэтому количество программных интерфейсов само по себе мало говорит о качестве архитектуры.

Гораздо важнее границы ответственности: какие данные принадлежат конкретному компоненту, какие операции он выполняет самостоятельно и какие зависимости возникают при обращении к другим системам.

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

Обсуждение API быстро превращается в сравнение технологий. Но начинать проектирование с вопроса «REST или GraphQL?» — примерно то же самое, что выбирать инструмент до того, как сформулирована работа.

Поэтому сначала стоит определить ограничения: кто обращается к системе, какие данные нужны клиенту, как часто происходят обращения, насколько критична задержка, каким будет объём обмена. И только после этого выбирать подход.

Проблема масштабнее, чем может показаться. В упомянутом выше исследовании 93% команд сообщили хотя бы об одном препятствии для совместной работы с API. Среди распространённых причин:

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

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

То же относится к обработке ошибок. Подключённая система должна однозначно понимать результат обращения: выполнен ли запрос успешно, переданы ли некорректные данные, достаточно ли прав доступа или ошибка возникла на стороне сервера.

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

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

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