Help:Public API: Difference between revisions

From Svacer Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
m (add OpenAPI link instead of table)
Line 9: Line 9:
* Простой способ — 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 '{"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) всех запросов: <code>Authorization: Bearer <token></code>
Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code>


Основные сущности сервера это:
=== Базовые публичные запросы ===
* проекты (project) — идентифицируются по UUID
* ветка (branch)  — идентифицируются по UUID
* cнимки (snapshot)  — идентифицируются по UUID
* маркеры (markers) — идентифицируются по UUID
* пользователи (users) — идентифицируются по UUID
 
=== Публичные запросы ===


{| class="wikitable"
{| class="wikitable"
Line 40: Line 33:
| '''/api/public/help'''
| '''/api/public/help'''
| GET
| GET
| Дополнительная информация по REST API. Работает без авторизации.
| Дополнительная информация по public REST API. Работает без авторизации
|-
|-
| '''/api/health'''
| '''/api/health'''
| GET
| GET
| Проверка доступности сервера. Возвращает Status 200 OK если сервер работает
| Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает
|-
| '''/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 ===
Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger</code>
{| 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/public/snaphots/{snapshot_id}/update'''
| PUT
| Переименование снимка. Принимает JSON объект с полем name, задающим новое имя для снимка. Возвращает 200 OK в случае успеха.
|}


=== Не публичное API, которое в следующих релизах станет публичным ===
Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger
Эти методы API мы планируем сделать публичными в следующих релизах (к ним добавится префикс public).
{| class="wikitable"
|'''/api/projects/admin/{container_id}/update'''
| PUT
| Метод переименовывает проект или ветку. Body должно содержать JSON объект с полем "name" и "id", где id должно соответствовать container_id, а container_id соответствовать ID ветки или проекта.
|}


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

Revision as of 16:36, 17 November 2023

Публичные 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
  • Предпочтительный способ — 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 загруженного снимка

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