Удобное API начинается не с красивой схемы, а с уважения к тому, как клиент живёт с вашим контрактом каждый день.
Для реального проектирования глава показывает, как каскад запросов, полезная нагрузка, стабильность контрактов и выбор между BFF, GraphQL и REST делают API ближе к задачам клиента.
Для интервью и инженерных разборов она помогает обсуждать клиентский фасад без скатывания в избыточную кастомизацию под одного потребителя.
Практическая польза главы
Практика проектирования
Стройте API от задач клиента: меньше каскадных вызовов, понятная полезная нагрузка и стабильные контракты.
Качество решений
Выбирайте BFF, GraphQL или REST по профилю потребителей и частоте изменений интерфейса.
Аргументация на интервью
Показывайте, как боль клиента переводится в конкретные архитектурные решения.
Анализ отказов
Контролируйте риск избыточной кастомизации API под одного клиента.
Источник
Customer-friendly API
Конспект доклада о клиент-ориентированных API.
Эта статья родилась примерно в 2020 году, когда я объяснял серверным командам, что бесконечный набор отдельных точек входа не делает API удобным. Чтобы собрать один экран, клиентам иногда приходилось обращаться к десяткам обработчиков, что ломало UX и замедляло развитие продукта.
Customer-friendly API — это фасад, который отдаёт клиенту готовые данные под сценарий, а не заставляет его собирать ответ из множества сервисов.
В этой главе важен не сам фасад, а взгляд : как , , , , , и влияют на скорость продукта.
API удобно нам ≠ удобно клиентам
Взгляд серверной команды
- Команда видит набор и сервисов.
- Клиенты сами получают данные и знают слишком много о внутренней структуре.
- считается нормой.
Взгляд клиента
- Один экран собирается из нескольких API.
- Нужно выполнять и объединять ответы.
- Бизнес-композиция переезжает в клиентское приложение.
Почему мобильным особенно больно
Жёсткая связанность
Приложение зависит от формата, количества и порядка точек входа API.
Дублирование логики
Одинаковая агрегация данных реализуется отдельно для iOS и Android.
Непрофильная работа
отвлекает от UI/UX и клиентской логики.
Долгий цикл изменений
Любая правка в требует релиза приложения.
Решение: клиент-ориентированный фасад
Что делает фасад
- Один вместо каскада запросов.
- или сценарий, а не универсальный набор полей.
- переносится ближе к серверной стороне.
- без обязательного релиза клиента.
Результат
Клиент получает готовые данные одним запросом, а серверная сторона остаётся местом, где живёт бизнес-композиция и эволюция контрактов.
Клиенты
Web / Mobile
Фасад
BFF / GraphQL
Сервисы
Микросервисы
Два подхода к фасаду
BFF (Backend for Frontend)
Серверный слой под конкретный тип клиента: агрегирует данные, скрывает внутреннюю сложность и отдаёт контракт под экран.
GraphQL
Клиент выбирает форму ответа в рамках схемы и получает только нужные поля, если команда контролирует сложность запросов.
Матрица выбора
BFF
контрольGraphQL
гибкостьОценки относительные: больше контроля у BFF, больше свободы у GraphQL.
Контроль vs свобода
BFF = контроль на сервере
- Контракт под конкретный интерфейс.
- Проще контролировать задержку, кэширование и объём ответа.
- Меньше свободы у клиента — меньше случайных рисков.
GraphQL = свобода для клиента
- Клиент формирует запросы под экран.
- Удобно для сложных интерфейсов и экспериментов.
- Нужны ограничения, мониторинг и управление API.
Гибриды и практика
- GraphQL может быть фасадом над сервисами.
- BFF может использовать GraphQL для части данных.
- Шлюз API закрывает общие платформенные задачи, а BFF — клиентскую специфику.
Мини-чеклисты
API неудобно клиенту
- Один экран требует 5-15 запросов.
- Клиент объединяет ответы разных сервисов.
- Формат данных меняется только через релиз клиента.
- У разных клиентов повторяется одна и та же агрегация данных.
- Растёт число временных адаптеров и обходных решений.
Когда подходит BFF
- Разным клиентам нужны разные формы .
- Мобильные релизы дорогие и редкие.
- Микросервисы создают .
- Нужно изолировать изменения и дать автономию UI-команде.
Когда полезен GraphQL
- Сложный интерфейс и много вариантов представлений.
- Нужна самодокументируемая схема и типизированные запросы.
- Команда готова инвестировать в ограничения, мониторинг и контроль запросов.
Вывод и рекомендации
Если нужен базовый и контролируемый способ сделать API удобным для клиента, BFF чаще выигрывает: он концентрирует контракт, снижает число вызовов и упрощает эволюцию клиентов.
Связанные главы
- Web API Design: The Missing Link (short summary) - REST-практики и дизайн клиентских контрактов: как структурировать URL, ссылки и полезную нагрузку под реальные сценарии.
- Learning GraphQL (short summary) - Альтернатива бэкенду для фронтенда с выборкой данных под управлением клиента и другими компромиссами по контролю и гибкости.
- API Gateway - Шлюз API для маршрутизации, авторизации и ограничения запросов, который дополняет клиентский фасад на уровне платформы.
- Continuous API Management (short summary) - Операционное управление жизненным циклом API: версии, управление API и эволюция контрактов между командами.
- API Design Patterns (short summary) - Паттерны контрактного дизайна, помогающие сделать клиентские API предсказуемыми и устойчивыми к изменениям.
- API Security Patterns - Практики безопасности для публичных и внутренних API: авторизация, политики доступа и снижение рисков интеграции.
- Паттерны межсервисной коммуникации - Как клиентский фасад сочетается с внутренними сервисными контрактами и снижает сложность интеграций.