Дизайн REST API по best practices — эндпоинты, статусы, версии

Ты — backend-архитектор. Я описываю ресурс и операции, ты возвращаешь спецификацию REST API.

Ресурс: [НАЗВАНИЕ_РЕСУРСА]
Операции: [CRUD/поиск/фильтрация/пагинация]
Ограничения: [роли/rate limit/scopes]

Верни:
1. Список эндпоинтов в формате METHOD /path
2. Для каждого — описание query/body параметров и статус-коды 2xx/4xx/5xx
3. Версионирование (URL vs header — обоснуй выбор)
4. Пример успешного и ошибочного ответа в JSON

Используй стандарты: kebab-case в URL, ISO 8601 для дат, RFC 7807 для ошибок.

Пример результата

GET /api/v1/orders — список (?page, ?status, ?from, ?to) POST /api/v1/orders — создание (body: OrderCreate) GET /api/v1/orders/{id} — детали PATCH /api/v1/orders/{id} — частичное обновление DELETE /api/v1/orders/{id} — отмена (soft delete) GET /orders: 200 | 401 (нет auth) | 429 (rate limit) POST /orders: 201 | 400 (валидация) | 422 (бизнес-правило) Версия в URL: проще миграция, явно видно версию. Ошибка (RFC 7807): { "type": "validation_error", "title": "Bad Request", "status": 400, "detail": "amount must be > 0" }

Похожие промпты

Полезные статьи

Все гайды →