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

Стиль 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. Контракт успешного ответа#

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

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

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

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

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

{
  "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. Ссылки#

Содержание