re:re:actable
Урок 043 минуты чтения

Как спроектировать 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-service

BFF уменьшает число запросов с клиента, скрывает внутренние сервисы и позволяет хранить токены сервисов на сервере.

Ошибки

{
  "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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам