REST API. Общие сведения

REST API позволяет:

• получить данные (GET-запросы);
• создать новые элементы данных (POST-запросы);
• изменить данные (PUT-запросы);
• удалить данные (DELETE-запросы);
• обновить данные (PATCH-запросы).

Для передачи команд через  REST API может использоваться утилита curl. 

Curl -  кроссплатформенная служебная программа командной строки, позволяющая взаимодействовать с множеством различных серверов по множеству различных протоколов с синтаксисом URL.

При работе с внешней утилитой curl возникает ряд особенностей:

• для отправки запроса GET использовать опцию -X 'GET';
• для отправки запроса DELETE использовать опцию -X 'DELETE';
• для отправки запроса PUT использовать опцию -X 'PUT';
• для отправки запроса POST использовать опцию -X 'POST';
• для отправки запроса PATCH использовать опцию -X 'PATCH'.

Возвращаемые форматы задаются заголовком accept, например:

curl ... -H "accept:application/json"

Пример POST-запроса:

curl -X 'POST' \
  'http://disp.termidesk.local/api/webui/v1/servicespools' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: 7bjqtodywjd69dkpdta9ncqprifkr3pu' \ 
  -d '{
  "name": "string",
  "comments": "string",
  "service_id": "string",
  "osmanager_id": "string",
  "image_id": "string",
  "help_url": "string",
  "servicesPoolGroup_id": "string",
  "cache_l1_srvs": 2147483647,
  "cache_l2_srvs": 2147483647,
  "max_srvs": 2147483647,
  "debug_mode": true,
  "backup": true,
  "fallbackAccess": "string"
}'

Результирующий формат указывается в ответном заголовке content-type.

Перед использованием REST API нужно получить токен (-H 'X-Auth-Token: 7bjqtodywjd69dkpdta9ncqprifkr3pu' из примера выше), который необходимо подставлять во все последующие запросы, кроме запросов health. 

• выполнить URL-команду: http://disp.termidesk.local/api/auth/draft/authenticators;
• запомнить значения параметров authUuid, authSmallName, auth;
• выполнить URL-команду:  http://disp.termidesk.local/api/auth/v1/legacy/login и заполнить экранные поля «Логин», «Пароль», «Название аутентификатора» (значение параметра auth из предыдущей команды), «UUID аутентификатора» (значение параметра authUuid из предыдущей команды), «Короткое название аутентификатора» (значение параметра authSmallName из предыдущей команды).

В приведенных командах disp.termidesk.local - сетевой адрес или полное доменное имя узла диспетчера Termidesk.

Для запросов проверки состояния сервера /api/health используется токен, определенный в конфигурационном файле /etc/opt/termidesk-vdi/termidesk.conf в значении переменной HEALTH_CHECK_ACCESS_KEY.

/api/<module>/<ver>/<name>/,

где:

<module> - наименование модуля, реализованного в REST API;

<ver> - версия;

<name> - наименование элемента. После наименования элемента также могут быть включены уникальные номера объектов и наименования других элементов.

В REST API реализовано следующее логическое разделение на модули:

• «agent» - модуль взаимодействия с компонентом «Агент» виртуального рабочего места (ВРМ);
• «auth» - модуль для аутентификации пользователей веб-интерфейса;
• «client» - модуль взаимодействия с компонентом «Клиент»;
• «external/rubackup» - модуль для интеграции с системой резервного копирования RuBackup;
• «health» - модуль проверки состояния Termidesk;
• «webui» -  модуль управления функциями, доступными через веб-интерфейс Termidesk;
• «wsproxy» - модуль взаимодействия с компонентом «Шлюз».

Список модулей API, предоставляемого сервером, может быть получен URL-командой /api/discover/.

Пример команды через curl:

curl -X 'GET' \
  'http://disp.termidesk.local/api/discover/' \
  -H 'accept: application/json' \
  -H 'X-Auth-Token: 7bjqtodywjd69dkpdta9ncqprifkr3pu'

По нажатию кнопки [Try it out]  в пространстве команд какого-либо модуля можно составить запрос и отправить его на выполнение кнопкой [Execute]. После нажатия будет отображена также команда для запроса через curl.

Для ввода токена доступа к определенным командам необходимо нажать кнопку [Authorize] и ввести необходимые ключи:

• «bearerAuth» - токен для аутентификации в модулях раздела «external». Получить токен можно в модуле «auth» по URL: /external/login;
• «legacyTokenAuth» - альтернативный способ аутентификации в модулях раздела «webui». Может быть получен в модуле «auth» по URL: /legacy/login. Наименование в заголовках запросов: X-Auth-Token;
• «healthTokenAuth» - токен для аутентификации в модулях раздела «health». Указывается в формате: Token <значение>. Значение токена определено в конфигурационном файле /etc/opt/termidesk-vdi/termidesk.conf, в значении переменной HEALTH_CHECK_ACCESS_KEY.