Help:Public API

From Svacer Wiki
Revision as of 17:16, 27 November 2024 by Akuzmin (talk | contribs) (add public_api/management/containers page link)

(diff) ← Older revision | Approved revision (diff) | Latest revision (diff) | Newer revision → (diff)

Публичные REST запросы

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой /api/some/request/v2.

Получение токена

Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:

  • Простой способ — POST запрос с basic auth на /api/login, который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
curl -X POST -u admin:admin http://svacer.example.com/api/login
  • Предпочтительный способ — POST запрос на /api/public/login с передачей данных в теле запроса, как описано ниже. Пример:
curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login

Полученный токен надо добавлять в header всех запросов: Authorization: Bearer <token>

Базовые публичные запросы

/api/public/login POST Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом: 
 {
   "auth_type": "string",
   "server": "string"
   "login": "string",
   "password": "string"
 }
  • auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer
  • server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если "auth_type": "ldap", в иных случаях его можно не указывать
  • login — логин пользователя, обязательное поле
  • password — пароль пользователя, обязательное поле
/api/public/help GET Дополнительная информация по public REST API. Работает без авторизации
/api/health GET Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает

Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу /api/public/swagger/

Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/

Управление контейнерами

См. Help:Public API/management/containers

Примеры использования public REST API

Получение URL загруженного снимка

Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.

Скачайте и распакуйте get_link.zip

Запрос: 

python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash

Ответ: 

http://svacer.example.com:8080/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d
Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:Public_API&oldid=2400"