Проектирование REST API

Хороший API — предсказуемый: одни и те же правила во всех эндпоинтах, понятные статусы и выдача по частям. Разбираем практику, которой ждут на реальных проектах.

Статусы и формы ответов

• 2xx — успех: 200 (ок), 201 (создано), 204 (пусто после удаления);
• 4xx — ошибка клиента: 400 (невалидно), 401 (не авторизован), 403 (запрещено), 404 (нет);
• 5xx — ошибка сервера: 500 (сбой), 502/503 (прокси/сервис недоступен).

// Стандартная форма ошибки
{
  "error": "VALIDATION",
  "message": "email обязательное поле",
  "fields": { "email": "пустое значение" }
}

Пагинация

// GET /api/v1/posts?limit=20&offset=40
{
  "data": [/* записи */],
  "pagination": { "limit": 20, "offset": 40, "total": 133 }
}

// Cursor-вариант (устойчивее к добавлениям)
// GET /api/v1/posts?limit=20&cursor=eyJ...  →  data + nextCursor

Версионирование и OpenAPI

• в URL с самого начала: /api/v1/… — добавление v2 не сломает старых клиентов;
• OpenAPI/Swagger — описание контракта: клиенты генерируют клиенты-обёртки и документацию автоматически;
• именование сущностей существительными во множественном числе: /posts, не /getAllPosts.