REST API

Для выполнения API-запросов в заголовке Authorization используется токен доступа формата Bearer. Описание процедуры получения токена доступа содержится в статье «Профиль пользователя».

Запросы к API v2 выполняются по базовому URL (<domain> – доменное имя модуля управления облаком):

https://<domain>/api/v2

Документация API модуля управления облаком (Swagger) доступна по адресу (<domain> – доменное имя модуля управления облаком):

https://<domain>/docs/api

Постраничный вывод

Метод API GET поддерживает постраничный вывод (пагинацию). Возврат результатов запроса с использованием постраничного вывода происходит по страницам, что снижает нагрузку на сервер. Количество результатов на страницу определяется заголовком запроса. Постраничный вывод используется для всех списковых запросов с методом GET.

Ниже приведены примеры запросов получения форматированного списка заявок через cURL с использованием постраничного вывода.

Статус постраничного вывода определяется значением заголовка логического типа X-Paginate.

По умолчанию заголовок X-Paginate имеет значение true, что соответствует включенному постраничному выводу, и размеру страницы 100 результатов:

curl -s -f -S -X 'GET' \
"https://${url_api}/api/v2/requests" \
-H ‘accept: application/json’ \
-H ‘X-Paginate: true’ \
-H "Authorization: Bearer ${token}" | jq

url_api – значение URL API. token – значение токена авторизации для запроса API

Значение false заголовка X-Paginate отключает постраничный вывод. Возвращаются сразу все результаты запроса:

curl -s -f -S -X 'GET' \
"https://${url_api}/api/v2/requests" \
-H ‘accept: application/json’ \
-H ‘X-Paginate: false’ \
-H "Authorization: Bearer ${token}" | jq

При включенном постраничном выводе значение заголовка X-Paginate-Size типа int определяет количество возвращаемых результатов на страницу. Данный запрос возвращает первую страницу с 50 результатами:

curl -s -f -S -X 'GET' \
"https://${url_api}/api/v2/requests" \
-H ‘accept: application/json’ \
-H ‘X-Paginate: true’ \
-H ‘X-Paginate-Size: 50’ \
-H "Authorization: Bearer ${token}" | jq

Запрос дополнительно возвращает метаданные с информацией об общем количестве результатов запроса и, при наличии, параметры запроса других страниц.

Данный запрос вернет третью страницу результатов с размером страницы 50:

curl -s -f -S -X 'GET' \
"https://${url_api}/api/v2/requests?page=3" \
-H ‘accept: application/json’ \
-H ‘X-Paginate: true’ \
-H ‘X-Paginate-Size: 50’ \
-H "Authorization: Bearer ${token}" | jq

Выполнение запросов REST API от имени другого пользователя

Для выполнения запроса REST API от имени другого пользователя используется заголовок X-Run-As. Токен, с которым выполняется запрос, должен иметь разрешение «Вход под другим пользователем». В заголовке X-Run-As указывается ID пользователя, от имени которого выполняется запрос.

Ниже приведен пример выполнения запроса от имени пользователя с ID=2. Результат содержит список задач, созданных пользователем с ID=2:

curl -s -f -S -X 'GET' \
"https://${url_api}/api/v2/requests" \
-H "accept: application/json" \
-H 'X-Run-As: 2' \
-H "Authorization: Bearer ${token}" | jq