Удобное 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, и дальше чинят в двух местах.
Непрофильная работа
Вместо интерфейса и клиентской логики команда занимается — работой, которая по сути серверная.
Долгий цикл изменений
Любая правка в упирается в релиз приложения, а его в магазине ждут днями.
Решение: клиент-ориентированный фасад
Что делает фасад
- Один вместо каскада запросов.
- или сценарий, а не универсальный набор полей.
- переносится ближе к серверной стороне.
- без обязательного релиза клиента.
Результат
Клиент получает готовые данные одним запросом и больше не знает, из скольких сервисов они собраны. Бизнес-композиция и эволюция контрактов остаются на серверной стороне — там, где их дешевле менять.
Клиенты
Web / Mobile
Фасад
BFF / GraphQL
Сервисы
Микросервисы
Два подхода к фасаду
BFF (Backend for Frontend)
Бэкенд для фронтенда (BFF) — серверный слой под конкретный тип клиента: он агрегирует данные, прячет внутреннюю сложность и отдаёт контракт ровно под экран. Цена — отдельный слой, который кто-то должен поддерживать.
GraphQL
Здесь форму ответа выбирает клиент: в рамках схемы он берёт только нужные поля. Свобода работает, пока команда удерживает сложность запросов под контролем — иначе один тяжёлый запрос кладёт серверную сторону.
Матрица выбора
BFF
контрольGraphQL
гибкостьОценки относительные: больше контроля у бэкенда для фронтенда (BFF), больше свободы у GraphQL.
Контроль vs свобода
Бэкенд для фронтенда (BFF) = контроль на сервере
- Контракт под конкретный интерфейс.
- Проще контролировать задержку, кэширование и объём ответа.
- Меньше свободы у клиента — меньше случайных рисков.
GraphQL = свобода для клиента
- Клиент формирует запросы под экран.
- Удобно для сложных интерфейсов и экспериментов.
- Нужны ограничения, мониторинг и управление API.
Гибриды и практика
- GraphQL может быть фасадом над сервисами.
- Бэкенд для фронтенда (BFF) может использовать GraphQL для части данных.
- Шлюз API закрывает общие платформенные задачи, а бэкенд для фронтенда (BFF) — клиентскую специфику.
Мини-чеклисты
API неудобно клиенту
- Один экран требует 5-15 запросов.
- Клиент объединяет ответы разных сервисов.
- Формат данных меняется только через релиз клиента.
- У разных клиентов повторяется одна и та же агрегация данных.
- Растёт число временных адаптеров и обходных решений.
Когда подходит бэкенд для фронтенда (BFF)
- Разным клиентам нужны разные формы .
- Мобильные релизы дорогие и редкие.
- Микросервисы создают .
- Нужно изолировать изменения и дать автономию UI-команде.
Когда полезен GraphQL
- Сложный интерфейс и много вариантов представлений.
- Нужна самодокументируемая схема и типизированные запросы.
- Команда готова инвестировать в ограничения, мониторинг и контроль запросов.
Вывод и рекомендации
Как стартовая точка бэкенд для фронтенда (BFF) чаще выигрывает: он держит контракт в одном месте, снижает число вызовов и упрощает эволюцию клиентов. GraphQL берут, когда гибкость интерфейса важнее контроля и команда готова платить за неё ограничениями и мониторингом запросов.
Связанные главы
- 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: авторизация, политики доступа и снижение рисков интеграции.
- Паттерны межсервисной коммуникации - Как клиентский фасад сочетается с внутренними сервисными контрактами и снижает сложность интеграций.