RestApiDeveloperGuide: различия между версиями
(не показаны 4 промежуточные версии этого же участника) | |||
Строка 7: | Строка 7: | ||
(работа с определениями БП, БП, задачами, пользователями, отношениями, логами и т.д.). | (работа с определениями БП, БП, задачами, пользователями, отношениями, логами и т.д.). | ||
OpenApi спецификация находится | OpenApi спецификация находится [https://github.com/processtech/runawfe-free-server/blob/master/wfe-restapi-client/src/main/resources/api-docs.json тут], | ||
исходный код - | исходный код - [https://github.com/processtech/runawfe-free-server/tree/master/wfe-restapi/src/main/java/ru/runa/wfe/rest/impl тут]. | ||
Аутентификация происходит стандартным способом - посредством передачи JWT в заголовке Authorization (e.g. '-H "Authorization: Bearer ${jwt}")'). | Аутентификация происходит стандартным способом - посредством передачи JWT в заголовке Authorization (e.g. '-H "Authorization: Bearer ${jwt}")'). | ||
Авторизация - путем передачи данных (зачастую логина и пароля) в соответствующие методы и получения JWT (подробнее - | Авторизация - путем передачи данных (зачастую логина и пароля) в соответствующие методы и получения JWT (подробнее - [[RestApiDeveloperGuide#.23_Auth_API|в отдельном блоке]]). | ||
Базовый урл - <b>/restapi</b> (например, для localhost - localhost/restapi/) | Базовый урл - <b>/restapi</b> (например, для localhost - localhost/restapi/) | ||
Строка 37: | Строка 37: | ||
* <b>/{id}</b> - получение определения БП по id | * <b>/{id}</b> - получение определения БП по id | ||
== {{Title|apis-process|Process API}} == | |||
Базовый урл - <b>/process</b> (например, для localhost - localhost/restapi/process) | |||
Отвечает за работу с экземплярами БП, основные методы: | |||
* <b>/start</b> - запуск БП по названию (последней доступной версии определения) | |||
* <b>/{definitionId}/start</b> - запуск БП по id определения | |||
* <b>/list</b> - получение экземпляров БП по заданному фильтру | |||
* <b>/{id}</b> - получение экземпляра БП по id | |||
== {{Title|apis-task|Task API}} == | |||
Базовый урл - <b>/task</b> (например, для localhost - localhost/restapi/task) | |||
Отвечает за работу с задачами, основные методы: | |||
* <b>/my</b> - получение собственных задач (пользователя, JWT которого передается в Authorization) | |||
* <b>/{id}/complete</b> - выполнение задачи | |||
* <b>/list</b> - получение задач по заданному фильтру | |||
* <b>/{id}</b> - получение задачи по id | |||
= {{Title|examples|Примеры}} = | = {{Title|examples|Примеры}} = | ||
Строка 104: | Строка 121: | ||
} | } | ||
</pre> | </pre> | ||
=== {{Title|java_start_process|Запуск процесса по названию}} === | |||
<pre> | |||
import org.eclipse.jetty.client.HttpClient; | |||
... | |||
try { | |||
HttpClient httpClient = new HttpClient(); | |||
httpClient.start(); | |||
String token = getToken(httpClient); | |||
String startedProcessId = httpClient.newRequest("localhost/restapi/" + "process/start") | |||
.method(HttpMethod.PUT) | |||
.header("Authorization", "Bearer " + token) | |||
.param("name", "Simple process") | |||
.send().getContentAsString(); | |||
httpClient.stop(); | |||
} catch (Exception e) { | |||
// exception handling | |||
} | |||
</pre> | |||
=== {{Title|java_complete_task|Выполнение задачи}} === | |||
<pre> | |||
import org.eclipse.jetty.client.HttpClient; | |||
... | |||
try { | |||
HttpClient httpClient = new HttpClient(); | |||
httpClient.start(); | |||
String token = getToken(httpClient); | |||
Long taskId = getTaskId(httpClient); | |||
httpClient.newRequest("localhost/restapi/" + taskId + "/complete") | |||
.method(HttpMethod.POST) | |||
.header("Content-type", "application/json") | |||
.header("Authorization", "Bearer " + token) | |||
.content(new StringContentProvider("{}")) | |||
.send().getContentAsString(); | |||
httpClient.stop(); | |||
} catch (Exception e) { | |||
// exception handling | |||
} | |||
</pre> | |||
== {{Title|curl_examples|Curl}} == | == {{Title|curl_examples|Curl}} == | ||
=== {{Title|curl_auth|Авторизация по логину и паролю}} === | === {{Title|curl_auth|Авторизация по логину и паролю}} === | ||
Строка 118: | Строка 176: | ||
-F "categories=" \ | -F "categories=" \ | ||
--data-binary "@$(pwd)/bp.par" | --data-binary "@$(pwd)/bp.par" | ||
</pre> | |||
=== {{Title|curl_start_process|Запуск процесса по названию}} === | |||
<pre> | |||
curl -X PUT "http://localhost/restapi/process/start" \ | |||
-H "Authorization: Bearer ${jwt}" \ | |||
-F "name=Simple process" | |||
</pre> | |||
=== {{Title|curl_complete_task|Выполнение задачи}} === | |||
<pre> | |||
curl -X POST "http://localhost/restapi/${task_id}/complete" \ | |||
-H "Content-Type: application/json" \ | |||
-H "Authorization: Bearer ${jwt}" \ | |||
-d '{}' | |||
</pre> | </pre> |
Текущая версия на 11:53, 7 октября 2024
Руководство по работе с Rest API
Версия 4.6.0
© 2015-2023, ООО "Процессные технологии"
# Введение
RunaWFE REST API - restful API RunaWFE–сервера, предоставляющий доступ к большинству доступных операций внутри системы (работа с определениями БП, БП, задачами, пользователями, отношениями, логами и т.д.).
OpenApi спецификация находится тут,
исходный код - тут.
Аутентификация происходит стандартным способом - посредством передачи JWT в заголовке Authorization (e.g. '-H "Authorization: Bearer ${jwt}")').
Авторизация - путем передачи данных (зачастую логина и пароля) в соответствующие методы и получения JWT (подробнее - в отдельном блоке).
Базовый урл - /restapi (например, для localhost - localhost/restapi/)
# Краткая информация об основных API
Краткая информация об основных API
# Auth API
Базовый урл - /auth (например, для localhost - localhost/restapi/auth).
Отвечает за авторизацию пользователей и содержит 3 метода:
- /basic - авторизация по логину и паролю
- /kerberos - авторизация по kerberos токену
- /trusted - авторизация по trusted принципу
# Definition API
Базовый урл - /definition (например, для localhost - localhost/restapi/definition).
Отвечает за работу с определениями БП, основные методы:
- / - загрузка нового определения БП
- /list - получение определений БП по заданному фильтру
- /{id} - получение определения БП по id
# Process API
Базовый урл - /process (например, для localhost - localhost/restapi/process)
Отвечает за работу с экземплярами БП, основные методы:
- /start - запуск БП по названию (последней доступной версии определения)
- /{definitionId}/start - запуск БП по id определения
- /list - получение экземпляров БП по заданному фильтру
- /{id} - получение экземпляра БП по id
# Task API
Базовый урл - /task (например, для localhost - localhost/restapi/task)
Отвечает за работу с задачами, основные методы:
- /my - получение собственных задач (пользователя, JWT которого передается в Authorization)
- /{id}/complete - выполнение задачи
- /list - получение задач по заданному фильтру
- /{id} - получение задачи по id
# Примеры
# Java
В примерах ниже для удобства будут использоваться
- Jackson (для сериализации в JSON),
- клиентская библиотека wfe-restapi (содержащая все необходимые dto),
- а также Jetty (для выполнения HTTP запросов), пример зависимостей:
<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </dependency> <dependency> <groupId>ru.runa.wfe</groupId> <artifactId>wfe-restapi</artifactId> <classifier>client</classifier> </dependency> <dependency> <groupId>org.eclipse.jetty.websocket</groupId> <artifactId>javax-websocket-client-impl</artifactId> </dependency>
# Авторизация по логину и паролю
import com.fasterxml.jackson.databind.ObjectMapper; import org.eclipse.jetty.client.HttpClient; import ru.runa.wfe.rest.dto.WfeCredentials; ... try { HttpClient httpClient = new HttpClient(); httpClient.start(); WfeCredentials credentials = new WfeCredentials(); credentials.setLogin("Administrator"); credentials.setPassword("wf"); String token = httpClient.POST("localhost/restapi/" + "auth/basic") .header("Content-type", "application/json") .content(new StringContentProvider(new ObjectMapper().writeValueAsString(credentials))) .send().getContentAsString(); httpClient.stop(); } catch (Exception e) { // exception handling }
# Загрузка нового определения БП
import org.eclipse.jetty.client.HttpClient; ... try { HttpClient httpClient = new HttpClient(); httpClient.start(); String token = getToken(httpClient); byte[] file = Files.readAllBytes(Paths.get(System.getProperty("user.dir") + "bp.par")); httpClient.newRequest("localhost/restapi/" + "definition/") .method(HttpMethod.PUT) .header("Content-type", "multipart/form-data") .header("Authorization", "Bearer " + token) .param("categories", "") .content(new BytesContentProvider(file)) .send().getContentAsString(); httpClient.stop(); } catch (Exception e) { // exception handling }
# Запуск процесса по названию
import org.eclipse.jetty.client.HttpClient; ... try { HttpClient httpClient = new HttpClient(); httpClient.start(); String token = getToken(httpClient); String startedProcessId = httpClient.newRequest("localhost/restapi/" + "process/start") .method(HttpMethod.PUT) .header("Authorization", "Bearer " + token) .param("name", "Simple process") .send().getContentAsString(); httpClient.stop(); } catch (Exception e) { // exception handling }
# Выполнение задачи
import org.eclipse.jetty.client.HttpClient; ... try { HttpClient httpClient = new HttpClient(); httpClient.start(); String token = getToken(httpClient); Long taskId = getTaskId(httpClient); httpClient.newRequest("localhost/restapi/" + taskId + "/complete") .method(HttpMethod.POST) .header("Content-type", "application/json") .header("Authorization", "Bearer " + token) .content(new StringContentProvider("{}")) .send().getContentAsString(); httpClient.stop(); } catch (Exception e) { // exception handling }
# Curl
# Авторизация по логину и паролю
curl -X POST "http://localhost/restapi/auth/basic" \ -H "Content-Type: application/json" \ -d '{"login":"Administrator", "password":"wf"}'
# Загрузка нового определения БП
curl -X PUT "http://localhost/restapi/definition/" \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer ${jwt}" \ -F "categories=" \ --data-binary "@$(pwd)/bp.par"
# Запуск процесса по названию
curl -X PUT "http://localhost/restapi/process/start" \ -H "Authorization: Bearer ${jwt}" \ -F "name=Simple process"
# Выполнение задачи
curl -X POST "http://localhost/restapi/${task_id}/complete" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${jwt}" \ -d '{}'