REST API Design Guidelines

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

API версионируется через URL prefix: /api/v1/. Мажорная версия меняется при breaking changes.

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

Все ответы оборачиваются в { "data": ... }. Списки с пагинацией включают "meta" с total, per_page, current_page, last_page.

HTTP коды

200 — успех, 201 — создано, 204 — удалено, 400 — ошибка валидации, 401 — не авторизован, 403 — запрещено, 404 — не найдено, 422 — ошибка обработки, 500 — серверная ошибка.

Пагинация

Используйте cursor-based пагинацию для больших наборов данных. Offset-based для простых списков. Параметры: page, per_page (макс 50).

Фильтрация и поиск

Фильтры через query параметры: ?status=active&category=dev. Поиск через ?q=search_term. Сортировка через ?sort=name&order=asc.