Как спроектировать API между клиентом и сервером
На этой странице
На шаге Interface описывают контракт клиент — сервер: какие запросы делает клиент, с какими параметрами, в каком формате приходит ответ, как устроены пагинация, ошибки и обновления. Ключевые решения: REST или GraphQL, offset или cursor пагинация, нужен ли BFF (Backend for Frontend), как передавать частичные данные и как обрабатывать ошибки. API проектируют под экраны: один экран — как можно меньше последовательных запросов.
Вопрос
Как на frontend system design интервью спроектировать API? Как выбрать пагинацию, формат ответа и обработку ошибок и зачем нужен BFF?
Пример: лента
GET /api/feed?cursor=eyJpZCI6MTIzfQ&limit=20{
"items": [
{
"id": "p_123",
"author": { "id": "u_1", "name": "Анна", "avatarUrl": "https://cdn.example.com/a/u_1_64.webp" },
"text": "Привет!",
"media": [{ "type": "image", "url": "...", "width": 1200, "height": 800, "blurhash": "..." }],
"likeCount": 42,
"likedByMe": true,
"createdAt": "2026-10-17T10:00:00Z"
}
],
"nextCursor": "eyJpZCI6MTAzfQ",
"hasMore": true
}POST /api/posts создать пост
POST /api/posts/p_123/like поставить лайк (идемпотентно)
DELETE /api/posts/p_123/like снять лайк
GET /api/posts/p_123/comments?cursor=...Детали в ответе, которые упрощают фронтенд:
widthиheightмедиа — резервирование места и отсутствие CLS;likedByMe— не нужен отдельный запрос;- данные автора внутри поста или отдельным словарем — по выбору нормализации.
Пагинация
Offset (?page=3&limit=20) | Cursor (?cursor=abc&limit=20) | |
|---|---|---|
| Переход на произвольную страницу | да | нет |
| Новые элементы во время листания | дубли и пропуски | стабильно |
| Производительность на больших объемах | падает (OFFSET 100000) | стабильна |
| Где подходит | таблицы, админки, поиск со страницами | ленты, чаты, бесконечный скролл |
REST, GraphQL, BFF
| Подход | Когда |
|---|---|
| REST | простые ресурсы, HTTP-кеш и CDN, публичный API |
| GraphQL | разные клиенты, сложные связанные данные, нужно выбирать поля |
| BFF | сервер под конкретный фронтенд: объединяет микросервисы, режет лишние поля, держит токены |
Браузер ──▶ BFF (Next.js / Node) ──┬──▶ users-service
├──▶ posts-service
└──▶ media-serviceBFF уменьшает число запросов с клиента, скрывает внутренние сервисы и позволяет хранить токены сервисов на сервере.
Ошибки
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Текст поста слишком длинный",
"fields": { "text": "Максимум 5000 символов" }
}
}- HTTP-статусы по смыслу: 400/422 — ввод, 401 — нет сессии, 403 — нет прав, 404, 409 — конфликт, 429 — лимит, 5xx — сервер;
- стабильный машинный
codeдля логики и человекочитаемыйmessageдля UI; - для 429 и 503 — заголовок
Retry-After, клиент делает повтор с backoff.
Мутации
- идемпотентность: повторный лайк не создает второй лайк; для создания заказов —
Idempotency-Key; - оптимистичный ответ: сервер возвращает созданную сущность, клиент заменяет временную;
- конфликты: версия или
updatedAtдля защиты от перезаписи (ответ 409).
Что важно помнить
- Проектируйте API под экран: минимум последовательных запросов (водопадов), только нужные поля.
- Для лент и чатов — cursor-пагинация.
- Отдавайте размеры медиа и превью (blurhash, LQIP) — это сразу улучшает CLS и LCP.
- Обсудите ограничения: размер страницы, rate limit, таймауты.
- Связанные темы: REST ресурсы, пагинация, GraphQL.
Мини-шпаргалка
Опишите эндпоинты экрана, параметры, формат ответа. Ленты — cursor (nextCursor), таблицы — offset. REST — просто и кешируемо, GraphQL — гибкие поля, BFF — агрегация под фронтенд. Ошибки: статус + code + message + поля. Мутации идемпотентны, медиа с размерами.
Документация
GreatFrontEnd: Front End System Design Playbook, Slack Engineering: Evolving API Pagination, RFC 9457: Problem Details for HTTP APIs, Sam Newman: Backends For Frontends.