|
|
| (14 intermediate revisions by 2 users not shown) |
| Line 5: |
Line 5: |
| === Получение токена === | | === Получение токена === |
|
| |
|
| Для каждого публичного запроса нужен регистрационный токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами: | | Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами: |
|
| |
|
| * Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример: | | * Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример: |
| <pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre> | | <pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre> |
| * Предпочтительный способ — POST запрос на '''/api/public/login''' с [[#public-api-login|передачей данных в теле запроса]]. Пример: | | * Предпочтительный способ — POST запрос на '''/api/public/login''' с передачей данных в теле запроса, как описано [[#public-api-login|ниже]]. Пример: |
| <pre>curl -X POST -d '{"auth_type": "svacer", "login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre> | | <pre>curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre> |
|
| |
|
| Полученный токен добавляется в заголовок (Header) всех запросов (Authorization: Bearer <token>). | | Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code> |
|
| |
|
| Основные сущности сервера это:
| | === Базовые публичные запросы === |
| * проекты (project) — идентифицируются по UUID
| |
| * ветка (branch) — идентифицируются по UUID
| |
| * cнимки (snapshot) — идентифицируются по UUID
| |
| * маркеры (markers) — идентифицируются по UUID
| |
| * пользователи (users) — идентифицируются по UUID
| |
| | |
| === Публичные запросы === | |
|
| |
|
| {| class="wikitable" | | {| class="wikitable" |
| | '''/api/public/projects'''
| |
| | GET
| |
| | Возвращает список всех проектов с ветками
| |
| |-
| |
| | '''/api/public/projects/{project_id}/branch/{branch_id}/snapshots'''
| |
| | GET
| |
| | Возвращает список всех снимков конкретной ветки. Необходимые ID можно получить из предыдущего запроса.
| |
| |-
| |
| | '''/api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers'''
| |
| | GET
| |
| | Возвращает полную информацию обо всех маркерах конкретного снимка. У запроса есть опция '''?traces=true''' (по умолчанию false). Она добавит к каждому маркеру его трассу. Также доступна опция '''?checker_info=true''' (по умолчанию false). Она добавит к каждому маркеру severity и reliability детектора, к которому относится этот маркер. Иногда значение checker_severity в ответе может отсутствовать, это происходит если Svacer не имеет информации об этом детекторе: возможно он был удален из Svace или в данной версии еще не добавлен в Svacer. Для получения полной истории о разметке предупреждения следует использовать опцию '''?review_history=true'''
| |
| |-
| |
| | '''/api/public/diff?snapshot_v1=<id1>&snapshot_v2=<id2>&level=<number>'''
| |
| | GET
| |
| | Выполняет сравнение снимков с указанными id.
| |
| * Если snapshot_v2 отсутствует или пустой, то сравнение будет проведено с предыдущим снимком. Количество информации определяется переменной '''level''':
| |
| * 0 — только общая информация со статистикой;
| |
| * 1 — статистика и id маркеров;
| |
| * >1 (default) — полная информация.
| |
| |-
| |
| | '''/api/public/users/current'''
| |
| | PUT
| |
| | Обновляет текущего пользователя. Нужно передать объект с такими же полями, как в запросе на добавление пользователя.
| |
| |-
| |
| | '''/api/public/snapshots/{snapshot_id}/markers/suppress'''
| |
| | POST
| |
| | Подавление предупреждений. Тело:
| |
| {
| |
| ids: ["id1", "id2", ...]
| |
| rule: { /* any JSON object */ }
| |
| }
| |
| Поле ids задает список ID маркеров для подавления.
| |
| Поле rule задает специфичное для пользователя правило, согласно которому данные маркеры подавляются.
| |
| |-
| |
| | '''/api/public/snapshots/{snapshot_id}/markers/unsuppress'''
| |
| | POST
| |
| | Отмена подавления предупреждений. Тело:
| |
| { ids: ["id1", "id2", ...] }
| |
| Поле ids задает список ID маркеров для отмены подавления.
| |
| |-
| |
| | '''/api/public/snapshots/{snapshot_id}/markers/suppressed'''
| |
| | GET
| |
| | Отмена подавления предупреждений. Возвращает список подавленных маркеров в виде JSON массива.
| |
| |-
| |
| | '''/api/public/snapshots/{snapshot_id}/custom_fields/{field_name}'''
| |
| | GET
| |
| | Получение пользовательского атрибута у снимка. Результатом является JSON строка или массив строк.
| |
| |-
| |
| | '''/api/public/snapshots/{snapshot_id}/custom_fields'''
| |
| | GET
| |
| | Получение всех пользовательских атрибутов у снимка в виде одного JSON объекта.
| |
| |-
| |
| | '''/api/public/markers?filters={filter_data}&traces={true/false}&checker_info={true/false}&review_history={true/false}'''
| |
| | GET
| |
| | Получение списка маркеров по всем проектам/веткам/снимкам с учетом указанных в фильтре условий. При наличии больших объемов данных желательно максимально конкретизировать запрос во избежание проблем с производительностью. Фильтр передается в base64 кодировке.
| |
| <span id="public-api-markers-filters-data" />Общий вид фильтра следующий:
| |
| {
| |
| project:{
| |
| name:"имя проекта (регулярное выражение)",
| |
| id:"ID проекта (GUID)"
| |
| },
| |
| branch:{
| |
| name:"имя ветки (регулярное выражение)",
| |
| id:"ID ветки (GUID)"
| |
| },
| |
| snapshot:{
| |
| name:"имя снимка (регулярное выражение)",
| |
| id:"ID снимка (GUID)"
| |
| },
| |
| marker:{
| |
| severity:"серьезность маркера (регулярное выражение)",
| |
| file:"имя файла (регулярное выражение)",
| |
| review:"статус разметки (возможные значения: Undecided, Confirmed, Won't fix, False Positive, Unclear)",
| |
| checker:"имя маркера (регулярное выражение)"
| |
| }
| |
| }
| |
| Данный вид фильтра используется также в других запросах, при этом некоторые секции могут не учитываться (исходя из смысла запроса; например, при запросе снимков, фильтр на маркер не используется). Секции project, branch, snapshot игнорируются в случае их явного наличия в адресной строке. При одновременном указании name и id используется всегда id. ID всегда указывается точным значением.
| |
| |-
| |
| | '''/api/public/snapshots?filters={filter_data}'''
| |
| | GET
| |
| | Получение списка снимков по всем проектам/веткам с учетом указанных в фильтре условий. Формат фильтра см. выше.
| |
| |
| |
| |-
| |
| | '''/api/public/projects/{project_id}/branch/{branch_id}/fullmarkers?flat={true/other}'''
| |
| | GET
| |
| | Возвращает все маркеры (из всех снимков) для ветки с заданным branch_id. Если опция '''flat=true''', то результат возвращается как плоский массив маркеров со всеми данными (без структуризации по контейнеру и снимку). Маркеры возвращаются в виде:
| |
| [
| |
| {
| |
| container_id: "branch id",
| |
| "snapshot_id": [ {marker data}, ... ]
| |
| },
| |
| ...
| |
| ]
| |
| |-
| |
| | '''/api/public/projects/{project_id}/fullmarkers?flat={true/other}'''
| |
| | GET
| |
| | Возвращает все маркеры (из всех снимков и веток) для проекта с заданным project_id. Если опция '''flat=true''', то результат возвращается как плоский массив маркеров со всеми данными (без структуризации по контейнеру и снимку). Маркеры возвращаются в виде:
| |
| [
| |
| {
| |
| container_id: "branch id",
| |
| "snapshot_id": [ {marker data}, ... ]
| |
| },
| |
| ...
| |
| ]
| |
| |}
| |
|
| |
| === Публичные запросы, доступные только пользователям с ролью admin ===
| |
| {| class="wikitable"
| |
| | '''/api/public/users/admin/list'''
| |
| | GET
| |
| | Возвращает список пользователей. У запроса есть опция "roles=true" (по умолчанию false). Она добавит к каждому пользователю его роли.
| |
| |-
| |
| | '''/api/public/users/admin/add'''
| |
| | POST
| |
| | Добавляет нового пользователя. Нужно передать объект с полями login (обязательное), password (обязательное), firstname, lastname, middlename, email, passChangeRequest.
| |
| |-
| |
| | '''/api/public/users/admin/{user_id}'''
| |
| | PUT
| |
| | Обновляет пользователя с переданным ID. Нужно передать объект с такими же полями, как в запросе на добавление пользователя.
| |
| |-
| |
| | '''/api/public/users/admin/{user_id}'''
| |
| | DELETE
| |
| | Удаляет пользователя с переданным ID.
| |
| |-
| |
| | '''/api/public/users/admin/{user_id}/status'''
| |
| | PUT
| |
| | Устанавливает пользователю с переданным ID статус переданный в объекте вида {status:<int>}, где 0 — архивный, а 1 — активный.
| |
| |-
| |
| | '''/api/public/roles/admin/list'''
| |
| | GET
| |
| | Возвращает список ролей.
| |
| |-
| |
| | '''/api/public/roles/admin/add'''
| |
| | POST
| |
| | Добавляет новую роль. Нужно передать объект с полями name (обязательное), permissions (обязательное), где permissions — это массив объектов с полями target (обязательное) и action (обязательное).
| |
| |-
| |
| | '''/api/public/roles/admin/{role_id}'''
| |
| | PUT
| |
| | Обновляет роль с переданным ID. Нужно передать объект с такими же полями, как в запросе на добавление роли.
| |
| |-
| |
| | '''/api/public/roles/admin/{role_id}'''
| |
| | DELETE
| |
| | Удаляет роль с переданным ID.
| |
| |-
| |
| | '''/api/public/users/admin/{user_id}/roles'''
| |
| | PUT
| |
| | Добавляет или убирает роли пользователю с переданным ID. Нужно передать объект с полями user_id (обязательное), roles (обязательное), где roles — это массив объектов с такими же полями, как в запросе на добавление роли. У запроса есть обязательный параметр "action=add/delete". Опция "add" добавит роль пользователю, а "delete" — уберет.
| |
| |-
| |
| | '''/api/public/users/current'''
| |
| | PUT
| |
| | Обновление профиля текущего пользователя (того, с чьим токеном авторизации мы обращаемся к API). В body передается JSON объект с полями, аналогичными запросу на добавление нового пользователя
| |
| |-
| |
| | '''/api/public/users/admin/{user_id}/status'''
| |
| | PUT
| |
| | Установка статуса пользователя. Body должно содержать JSON объект вида {status:<int>} где значение статуса 0 или 1. Где 0 — "архивный" пользователь (неактивен, не может зайти в сервер), 1 — активный пользователь.
| |
| |-
| |
| | '''/api/public/exportPDF'''
| |
| | POST
| |
| | Создание PDF отчета по проекту. См. [[Help:ServerClient#Создание_PDF_отчета_для_проекта|Создание PDF отчета для проекта]].
| |
| |-
| |
| | '''/api/public/generateURLs'''
| |
| | POST
| |
| | Создание URL для маркера. Принимает JSON объект с полями
| |
| * markers: ["id1", "id2", ...] — список ID маркеров для генерации URL
| |
| * location: "<url>" — базовый URL на каком виден Svacer с точки зрения клиента
| |
| * type: "short|full" — опциональный атрибут для генерации короткого или полного URL. По умолчанию создаются полные URL
| |
| '''Результат работы команды''' — JSON объект с полями
| |
| * urls: ["url1", "url2", ...] — каждый URL соответствует ID маркеру в той же позиции во входных данных
| |
| * type: "short|full" — тип URL
| |
| |-
| |
| | '''/api/health'''
| |
| | GET
| |
| | Проверка доступности сервера. Возвращает Status 200 OK если сервер работает
| |
| |-
| |
| | '''/api/public/snaphots/{snapshot_id}/update'''
| |
| | PUT
| |
| | Переименование снимка. Принимает JSON объект с полем name, задающим новое имя для снимка. Возвращает 200 OK в случае успеха.
| |
| |-
| |
| | '''/api/public/login''' | | | '''/api/public/login''' |
| | POST | | | POST |
| | <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом: | | | <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом: |
| { | | { |
| "auth_type": "ldap", | | "auth_type": "string", |
| "server": "open_ldap", | | "server": "string" |
| "login": "user", | | "login": "string", |
| "password": "user", | | "password": "string" |
| "role": "admin"
| |
| } | | } |
| * auth_type — тип аутентификации ("svacer" или "ldap") | | * auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer |
| * server — имя ldap сервера, как он указан в конфигурационном файле ldap (поле name) при старте сервера. Поле можно опустить в случае использования "svacer" аутентификации | | * server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если <code>"auth_type": "ldap"</code>, в иных случаях его можно не указывать |
| * role — роль, с которой будет работать пользователь
| | * login — логин пользователя, обязательное поле |
| * login — имя пользователя | | * password — пароль пользователя, обязательное поле |
| * password — пароль пользователя | |
| |- | | |- |
| | '''/api/public/help''' | | | '''/api/public/help''' |
| | GET | | | GET |
| | Дополнительная информация по REST API. Работает без авторизации. | | | Дополнительная информация по public REST API. Работает без авторизации |
| | |- |
| | | '''/api/health''' |
| | | GET |
| | | Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает |
| |} | | |} |
|
| |
|
| === Не публичное API, которое в следующих релизах станет публичным ===
| | Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code> |
| Эти методы API мы планируем сделать публичными в следующих релизах (к ним добавится префикс public).
| | |
| {| class="wikitable"
| | Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/ |
| |'''/api/projects/admin/{container_id}/update'''
| | |
| | PUT
| | == Управление контейнерами == |
| | Метод переименовывает проект или ветку. Body должно содержать JSON объект с полем "name" и "id", где id должно соответствовать container_id, а container_id соответствовать ID ветки или проекта.
| | См. [[Help:Public API/management/containers]] |
| |}
| | |
| == Примеры использования public REST API == | | == Примеры использования public REST API == |
| === Использование public REST API для получения URL на загруженный снимок === | | |
| [[:File:get_link.py]] | | === Получение URL загруженного снимка === |
| | |
| | Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP. |
| | |
| | Скачайте и распакуйте [[Media:get_link.zip|get_link.zip]] |
|
| |
|
| Запрос: | | Запрос: |
| <code> python "get_link.py" --url http://hadokku.intra.ispras.ru:8081 --user admin --password admin --project bash </code> | | <pre>python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash</pre> |
|
| |
|
| Ответ: | | Ответ: |
| <code> http://hadokku.intra.ispras.ru:8081/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d </code> | | <pre>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</pre> |
