Help:Public API

From Svacer Wiki
Revision as of 18:00, 13 November 2023 by Akuzmin (talk | contribs)

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

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

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

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

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

Полученный токен добавляется в заголовок (Header) всех запросов (Authorization: Bearer <token>).

Основные сущности сервера это:

  • проекты (project) — идентифицируются по UUID
  • ветка (branch) — идентифицируются по UUID
  • cнимки (snapshot) — идентифицируются по UUID
  • маркеры (markers) — идентифицируются по UUID
  • пользователи (users) — идентифицируются по UUID

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

/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 кодировке.

Общий вид фильтра следующий: 

 {
   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

/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 отчета по проекту. См. Создание 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 POST Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом: 
 {
   "auth_type": "ldap",
   "server": "open_ldap",
   "login": "user",
   "password": "user",
   "role": "admin"
 }
  • auth_type — тип аутентификации ("svacer" или "ldap")
  • server — имя ldap сервера, как он указан в конфигурационном файле ldap (поле name) при старте сервера. Поле можно опустить в случае использования "svacer" аутентификации
  • role — роль, с которой будет работать пользователь
  • login — имя пользователя
  • password — пароль пользователя
/api/public/help GET Дополнительная информация по REST API. Работает без авторизации.

Не публичное API, которое в следующих релизах станет публичным

Эти методы API мы планируем сделать публичными в следующих релизах (к ним добавится префикс public).

/api/projects/admin/{container_id}/update PUT Метод переименовывает проект или ветку. Body должно содержать JSON объект с полем "name" и "id", где id должно соответствовать container_id, а container_id соответствовать ID ветки или проекта.

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

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

Скачайте и распакуйте Media: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=1447"