Help:Public API: Difference between revisions

Latest revision as of 18:55, 22 January 2024

Публичные 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/

Примеры использования 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

@@ Line 5: / Line 5: @@
 === Получение токена ===
-Для каждого публичного запроса нужен регистрационный токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:
+Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:
 * Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
@@ Line 40: / Line 40: @@
 |}
-Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger</code>
+Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code>
-Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger
+Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/
 == Примеры использования public REST API ==
@@ Line 48: / Line 48: @@
 === Получение URL загруженного снимка ===
-Скачайте и распакуйте [[Media:get_link.zip|get_link.zip]]
+Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.
+Скачайте и распакуйте [[Media:get_link.zip|get_link.zip]]
 Запрос: