Перейти к содержанию

Обзор API

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

Базовый URL

Все запросы к API следует отправлять на единый базовый URL.

  • On-premise (локальные или приватные облака): URL будет уникальным для вашей инсталляции. Уточните его у системных администраторов.

Все эндпоинты, описанные в документации, указываются относительно этого базового URL.

Аутентификация

API использует механизм Bearer Auth. Для каждого запроса необходимо передавать заголовок Authorization со значением в формате Bearer <токен>.

Как сгенерировать токен?

Подробная пошаговая инструкция находится на странице Аутентификация.

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

Номер версии включен в путь каждого эндпоинта (например, /v1/configs). Это гарантирует, что будущие обновления не нарушат обратную совместимость.

HTTP Статус-коды

API использует стандартные HTTP статус-коды для информирования о результате выполнения запроса.

Код Описание
200 OK Запрос успешно выполнен.
400 Bad Request Некорректный запрос (например, неверные параметры или структура).
401 Unauthorized Ошибка аутентификации (неверный, отсутствующий или просроченный токен).
403 Forbidden Доступ запрещен (недостаточно прав для выполнения операции).
404 Not Found Запрашиваемый ресурс не найден.
500 Internal Server Error Внутренняя ошибка на стороне сервера.

Обработка ошибок

При возникновении ошибки (статус-коды 4xx или 5xx) API возвращает стандартизированный JSON-объект.

Пример тела ответа при ошибке: 

{
  "message": "Authentication token is invalid or expired",
  "status": "error"
}

  • status (string): В случае ошибки всегда имеет значение error.
  • message (string): Человекочитаемое описание проблемы.

См. также