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

Как за пять минут набросать понятный контракт 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 против альтернатив

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

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

Итог

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