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

Спроектируй API для {{domain}}. Потребители: {{consumers}}.

1. Стиль

• REST — для CRUD-ориентированных ресурсов
• RPC (POST /verbs) — для действий-команд
• GraphQL — для гибких выборок с фронтенда
• Выбери один доминирующий стиль, не смешивай

2. Ресурсы

Перечисли. Для каждого:

• Имя (множественное, kebab-case в URL)
• Поля (с типами)
• Связи (1:1, 1:N, M:N)
• Lifecycle (создание, изменение, удаление, мягкое удаление?)

3. Эндпойнты

GET    /v1/resources           # список с пагинацией
GET    /v1/resources/:id       # один
POST   /v1/resources           # создать
PATCH  /v1/resources/:id       # частичное обновление
DELETE /v1/resources/:id       # удалить
POST   /v1/resources/:id:verb  # действие (например, :archive)

4. Параметры

• Пагинация: cursor-based (рекомендую) — ?cursor=...&limit=20
• Фильтры: ?status=active&owner_id=42
• Сортировка: ?sort=-created_at (минус = desc)
• Sparse fields: ?fields=id,name,status

5. Формат ответа

{
  "data": { ... } | [ ... ],
  "meta": { "next_cursor": "..." }
}

6. Ошибки

HTTP статус + структурированное тело:

{
  "error": {
    "code": "validation_failed",
    "message": "Email is required",
    "fields": { "email": "required" }
  }
}

Стандартные коды: 400 (validation), 401 (no auth), 403 (no permission), 404, 409 (conflict), 429 (rate limit), 500.

7. Версионирование

• В URL: /v1/ — простой и явный
• Не Accept: application/vnd.app.v1+json — сложно отлаживать
• Breaking changes только при смене major

8. Идемпотентность

• GET/HEAD/PUT/DELETE — идемпотентны по природе
• POST — клиент шлёт Idempotency-Key header, сервер кеширует ответ на N часов

9. Rate limits

• Заголовки: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• 429 при превышении
• Разные лимиты для разных tier'ов

10. Аутентификация

• Bearer-токен в Authorization: Bearer ...
• Не сессии для API (только для веб-клиента)

Документация: OpenAPI 3 спека → доки сгенерируются из неё.

Принципы

• Имена ресурсов — существительные, не глаголы
• Один способ сделать одну вещь
• Консистентность важнее красоты
• Совместимость на минор-уровне обязательна