Help:Public API: Difference between revisions
Mitrofanov (talk | contribs) |
|||
(13 intermediate revisions by 2 users not shown) | |||
Line 5: | Line 5: | ||
=== Получение токена === | === Получение токена === | ||
Для | Для каждого публичного запроса нужен регистрационный токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами: | ||
* Простой способ — 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''' с | * Предпочтительный способ — 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 '{"auth_type": "svacer", "login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre> | ||
Полученный токен | Полученный токен добавляется в заголовок (Header) всех запросов (Authorization: Bearer <token>). | ||
Основные сущности сервера это: | |||
* проекты (project) — идентифицируются по UUID | |||
* ветка (branch) — идентифицируются по UUID | |||
* cнимки (snapshot) — идентифицируются по UUID | |||
* маркеры (markers) — идентифицируются по UUID | |||
* пользователи (users) — идентифицируются по UUID | |||
=== Публичные запросы === | |||
{| 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" | {| 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": " | "auth_type": "ldap", | ||
"server": " | "server": "open_ldap", | ||
"login": " | "login": "user", | ||
"password": " | "password": "user", | ||
"role": "admin" | |||
} | } | ||
* auth_type — тип аутентификации | * auth_type — тип аутентификации ("svacer" или "ldap") | ||
* server — имя | * server — имя ldap сервера, как он указан в конфигурационном файле ldap (поле name) при старте сервера. Поле можно опустить в случае использования "svacer" аутентификации | ||
* login — | * role — роль, с которой будет работать пользователь | ||
* password — пароль пользователя | * login — имя пользователя | ||
* password — пароль пользователя | |||
|- | |- | ||
| '''/api/public/help''' | | '''/api/public/help''' | ||
| GET | | GET | ||
| Дополнительная информация по | | Дополнительная информация по REST API. Работает без авторизации. | ||
|} | |} | ||
=== Не публичное API, которое в следующих релизах станет публичным === | |||
Эти методы 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 == | ||
=== Использование public REST API для получения URL на загруженный снимок === | |||
=== | [[:File:get_link.py]] | ||
Запрос: | Запрос: | ||
<code> python "get_link.py" --url http://hadokku.intra.ispras.ru:8081 --user admin --password admin --project bash </code> | |||
Ответ: | Ответ: | ||
<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> |
Revision as of 13:44, 9 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 '{"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.
| |
/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 объект с полями
Результат работы команды — JSON объект с полями
|
/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" }
|
/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
Использование public REST API для получения URL на загруженный снимок
Запрос:
python "get_link.py" --url http://hadokku.intra.ispras.ru:8081 --user admin --password admin --project bash