Дизайн API: контракты эндпоинтов

~2 минуты · 2 примера · 3 вопроса

Как за пять минут набросать понятный контракт API, не утонув в деталях.

API-контракт — соглашение о том, какие эндпоинты есть, что они принимают и что возвращают; он связывает требования с моделью данных.

Что именно показывать

Не нужно описывать все эндпоинты. Достаточно 2–4 ключевых, покрывающих главные функции. Для каждого — метод, путь, основные параметры и форму ответа. Для сократителя ссылок:

POST /urls            { "long_url": "..." } -> { "short": "abc123" }
GET  /{short}         -> 302 Redirect на long_url
GET  /urls/{short}/stats -> { "clicks": 421 }

Пример тела ответа на создание ссылки:

{
  "short": "abc123",
  "long_url": "https://example.com/very/long/path",
  "created_at": "2026-06-22T10:00:00Z"
}

О чём упомянуть

Несколько деталей сразу повышают качество ответа: пагинация для списков (cursor лучше offset на больших данных), идемпотентность для POST (чтобы повтор запроса не создавал дубли), версионирование пути (/v1/), аутентификация. Не обязательно расписывать всё — достаточно назвать.

Как работает под капотом

API — это мост между нефункциональными требованиями и данными. Если требуется лента с бесконечной прокруткой, в контракте появляется cursor-пагинация (?cursor=...&limit=20), потому что offset на миллионах строк деградирует. Если редирект должен быть быстрым, эндпоинт GET /{short} читает из кэша, а не из БД. Контракт фиксирует, какие операции «горячие» и должны быть оптимизированы.

REST против альтернатив

СтильКогда уместен
RESTДефолт, ресурсная модель, кэшируемость
gRPCВнутренние сервисы, низкая латентность
GraphQLГибкие выборки клиента, агрегация
WebSocketРеалтайм: чат, уведомления

Частые ошибки

  • Расписывать десяток эндпоинтов вместо 2–4 ключевых.
  • Забыть про пагинацию у списочных эндпоинтов.
  • Использовать offset-пагинацию там, где данных миллионы.
  • Игнорировать идемпотентность для операций создания.

Итог

  • Покажите 2–4 ключевых эндпоинта: метод, путь, тело, ответ.
  • Назовите пагинацию (cursor), идемпотентность, версионирование, auth.
  • API фиксирует, какие операции горячие и требуют оптимизации.

Проверь себя

Три вопроса по уроку. Ответы никуда не идут — это для тебя.

1Сколько эндпоинтов разумно показать на собеседовании?

2Почему для ленты на миллионы записей предпочтительна cursor-пагинация, а не offset?

3Зачем POST-операции создания делать идемпотентными?