Основы API

Базовый URL, версионирование и общий формат ответов AISAR API: конверт данных, пагинация, ошибки и 204.

Этот раздел описывает общие соглашения AISAR API: базовый URL и версионирование, а также единый формат, в котором API возвращает данные, — конверт data, пагинацию, ошибки и пустые ответы. Соглашения одинаковы для всех групп эндпоинтов справочника REST.

Базовый URL

AISAR API размещён на отдельном субдомене. Все запросы к публичному REST API выполняются на базовый адрес с префиксом версии /v1 (без промежуточного сегмента /api):

text

https://api.aisar.app/v1

Номер версии — часть пути (/v1). Это текущая и единственная версия API; при выпуске несовместимых изменений появится новый префикс версии, а /v1 продолжит работать.

Помимо публичного /v1, платформа использует отдельную внутреннюю service-to-service поверхность для взаимодействия рантайм-сервисов с ядром. Она не входит в публичную интеграционную поверхность и в этом справочнике не описывается.

Ответ с одним объектом

Успешные ответы, возвращающие один ресурс, оборачивают его в поле data:

json

{
  "data": { "...": "..." }
}

Ответ со списком

Ответы со списком без пагинации возвращают массив в том же поле data:

json

{
  "data": [{ "...": "..." }]
}

Пагинированный список

Списки с пагинацией возвращают в data объект с массивом items и объектом pagination. Размер страницы задаётся query-параметром perPage (для большинства групп по умолчанию 20), номер страницы — page:

json

{
  "data": {
    "items": [{ "...": "..." }],
    "pagination": {
      "page": 1,
      "perPage": 20,
      "total": 150,
      "lastPage": 8
    }
  }
}

Поле	Описание
`page`	Номер текущей страницы.
`perPage`	Количество элементов на странице.
`total`	Общее количество элементов во всех страницах.
`lastPage`	Номер последней страницы.

Конверт ошибки

Ошибки не оборачиваются в data. Любой ответ с ошибкой содержит на верхнем уровне поле message с человекочитаемым описанием:

json

{
  "message": "Not found"
}

Полная таблица кодов состояния (401/403/404/422/429/5xx), пример ошибки тарифного гейта и рекомендации по повторным попыткам — в разделе «Ошибки».

204 No Content

Действия, которым нечего вернуть (например, удаление ресурса), отвечают статусом 204 No Content с пустым телом. Не пытайтесь разбирать тело таких ответов как JSON.