# Стиль API и контракт ответов

## Метаданные

- Документ ID: `REG-TECH-005`
- Версия: `0.1.1`
- Ответственный: `ООО "Аросса"`
- Статус: `Готово`

## 1. Базовые правила API

- Базовый префикс всех публичных REST endpoint: `/api/v1`.
- Имена ресурсов: `kebab-case`, множественное число (`accounts`, `status-events`, `device-profiles`).
- Ресурсные операции: `GET/POST/PUT/PATCH/DELETE`; командные операции оформляются как отдельный ресурс (`/api/v1/device-commands`).
- Нотация полей в JSON: `snake_case`.
- Временные метки: `UTC`, формат `RFC3339`.

## 2. Канонический маршрутный шаблон

- `GET /api/v1/<resource>/list` — выборка списка с фильтрацией/сортировкой/пагинацией.
- `GET /api/v1/<resource>/scheme` — схема/метаданные ресурса для UI.
- `GET /api/v1/<resource>/{id}` — получение одной сущности.
- `POST /api/v1/<resource>` — создание сущности или команды.
- `PATCH /api/v1/<resource>/{id}` — частичное изменение.
- `DELETE /api/v1/<resource>/{id}` — архивирование или удаление по политике ресурса.

## 3. Фильтрация, сортировка, пагинация

- Для всех `GET /api/v1/.../list` обязательны query-параметры: `limit`, `offset`.
- Базовые дополнительные query-параметры: `sort`, `order`, `q`.
- Значения `order`: `asc | desc`.
- Сложные фильтры передаются явными параметрами ресурса (`status`, `priority`, `source`, `tenant_id`).
- Пагинация в ответе возвращает `has_more` и следующий `offset`.

## 4. Контракт успешного ответа

Списочный ответ:

```json
{
  "items": [],
  "offset": 0,
  "limit": 20,
  "total": 0,
  "has_more": false,
  "meta": {
    "request_id": "req-20260304-001",
    "timestamp": "2026-03-04T17:50:00Z"
  }
}
```

Ответ по одной сущности:

```json
{
  "item": {},
  "meta": {
    "request_id": "req-20260304-002",
    "timestamp": "2026-03-04T17:50:03Z"
  }
}
```

## 5. Контракт ошибки

```json
{
  "error": {
    "code": "validation_error",
    "message": "Некорректное значение поля status",
    "details": [
      {
        "field": "status",
        "reason": "unsupported_value"
      }
    ]
  },
  "meta": {
    "request_id": "req-20260304-003",
    "timestamp": "2026-03-04T17:50:05Z"
  }
}
```

- HTTP-статусы: `200/201/204` для успешных операций, `400/401/403/404/409/422` для бизнес-ошибок, `500` для внутренних сбоев.
- Поле `code` фиксируется в реестре ошибок и не меняется в минорных версиях.

## 6. Идемпотентность и совместимость

- Для критичных `POST` операций (команды, создание задач, платежно-учетные операции) используется заголовок `Idempotency-Key`.
- При повторе запроса с тем же ключом сервис возвращает исходный результат без повторного выполнения операции.
- Обратно-совместимые изменения в `v1`: добавление полей, новых endpoint и новых значений перечислений.
- Несовместимые изменения: только в новом major-префиксе (`/api/v2`).

## 7. Ссылки

- [API и протоколы интеграции](api-and-protocols)
- [Модель учетных записей и доступа](account-model)
- [Информационная безопасность и защита данных](security-and-data-protection)
- [Единый API-контракт](../../backend_contracts)