Customer-friendly API: удобное API для клиентов

Удобное API начинается не с красивой схемы, а с уважения к тому, как клиент будет жить с вашим контрактом каждый день.

Для реального проектирования глава помогает увидеть, как минимальный fan-out, понятные payload, стабильные контракты и осознанный выбор между BFF, GraphQL и REST делают API ближе к задачам клиента, а не к внутренней структуре бэкенда.

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

Практическая польза главы

Практика проектирования

Стройте API от задач клиента: минимальный fan-out, понятные payload и стабильные контракты.

Качество решений

Выбирайте BFF/GraphQL/REST фасад по профилю потребителей и частоте изменений UI.

Interview articulation

Показывайте, как consumer pain map переводится в конкретные архитектурные решения.

Failure framing

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

Источник

Customer-friendly API

Конспект доклада о клиент-ориентированных API.

Перейти на сайт

Эта статья родилась примерно в 2020 году, когда я объяснял backend-командам, что «100500 отдельных endpoint-ов» не делают API удобным. Чтобы собрать один экран, клиентам иногда приходилось дергать по 50 разных handlers, что ломало UX и замедляло развитие продукта.

Customer-friendly API — это фасад, который отдаёт клиенту готовый сценарный payload, а не заставляет его собирать данные из множества сервисов.

API удобно нам ≠ удобно клиентам

Взгляд backend-команды

Есть набор endpoint-ов и сервисов.
Клиенты просто ходят за данными.
Композиция данных считается задачей фронта.

Взгляд клиента

Один экран = несколько разных API.
Нужно агрегировать и склеивать ответы.
Бизнес-композиция оказывается на клиенте.

Схема: как backend-команда видит клиентов вокруг единого backend — Как это выглядит глазами backend-команды: один backend и множество клиентов вокруг.

Почему мобильным особенно больно

Tight coupling

Приложение жёстко связано с форматом и количеством API.

Дублирование логики

Одинаковая агрегация данных реализуется отдельно для iOS и Android.

Непрофильная работа

Композиция данных на фронте отвлекает от UI/UX и клиентской логики.

Долгий цикл изменений

Любая правка в агрегации требует релиза приложения.

Схема: как мобильный клиент видит множество backend-систем — Как это выглядит глазами мобильного разработчика: один клиент и десятки связей с разными backend-ами.

Решение: клиент-ориентированный фасад

Что делает фасад

Один вызов вместо набора round-trip запросов.
Контракт под конкретный экран или сценарий.
Композиция данных переносится ближе к бэкенду.
Эволюция API без обязательного релиза клиента.

Результат

Клиент получает готовые данные в одном запросе, а бэкенд остаётся местом, где живёт бизнес-композиция и эволюция контрактов.

Клиенты

Web / Mobile

Фасад

BFF / GraphQL

Сервисы

Микросервисы

Два подхода к фасаду

BFF (Backend for Frontend)

Серверный слой под конкретный клиент: агрегирует данные и скрывает сложность.

Контроль контрактовПрогнозируемая производительностьЛокализация изменений

GraphQL

Клиент сам задаёт форму ответа в рамках схемы.

Гибкость UIТочность данныхМеньше over/under-fetching

Матрица выбора

BFF

контроль

Контроль контрактов5/5

Гибкость UI2/5

Предсказуемость перф4/5

Скорость экспериментов2/5

Требования к governance3/5

контроль

свобода

GraphQL

гибкость

Контроль контрактов2/5

Гибкость UI5/5

Предсказуемость перф2/5

Скорость экспериментов4/5

Требования к governance5/5

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

Контроль vs свобода

BFF = контроль на сервере

Контракт под конкретный UI.
Проще контролировать производительность и кэш.
Меньше свободы - меньше рисков.

GraphQL = свобода для клиента

Клиент формирует запросы под экран.
Гибко для сложных UI и экспериментирования.
Нужны ограничения, мониторинг и governance.

Гибриды и практика

GraphQL может быть фасадом над сервисами.
BFF может использовать GraphQL для части данных.
API Gateway закрывает кросс-сечения, а BFF - клиентскую специфику.

Мини-чеклисты

API неудобно клиенту

Один экран = 5-15 запросов.
Клиент склеивает ответы разных сервисов.
Формат данных меняется только через релиз клиента.
У разных клиентов копипаста агрегации.
Растёт число костылей и адаптеров.

Когда подходит BFF

Разные клиенты требуют разные payload-ы.
Мобильные релизы дорогие и редкие.
Микросервисы дают много downstream-вызовов.
Нужно изолировать изменения и дать автономию UI-команде.

Когда полезен GraphQL

Сложные UI и много вариантов представлений.
Хочется self-documentation и типизации схемы.
Есть готовность инвестировать в ограничения и контроль запросов.

Вывод и рекомендации

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

Связанные темы: Web API Design и Learning GraphQL.

Связанные главы

Web API Design: The Missing Link (short summary) - REST-практики и дизайн клиентских контрактов: как структурировать URL, ссылки и payload под реальные сценарии.
Learning GraphQL (short summary) - Альтернатива BFF с client-driven выборкой данных и другими компромиссами по контролю и гибкости.
API Gateway - Edge-слой для маршрутизации, auth и rate limiting, который дополняет клиентский фасад на уровне платформы.
Continuous API Management (short summary) - Операционное управление жизненным циклом API: версии, governance и эволюция контрактов между командами.
API Design Patterns (short summary) - Паттерны контрактного дизайна, помогающие сделать клиентские API предсказуемыми и устойчивыми к изменениям.
API Security Patterns - Security-практики для публичных и внутренних API: авторизация, policy enforcement и снижение рисков интеграции.
Паттерны межсервисной коммуникации - Как клиентский фасад сочетается с внутренними сервисными контрактами и снижает сложность интеграций.