RestApiDeveloperGuide: различия между версиями

Материал из RunaWFE
Перейти к навигации Перейти к поиску
 
(не показано 7 промежуточных версий этого же участника)
Строка 1: Строка 1:
{{PageHeading|Руководство по работе с Resr API}}
{{PageHeading|Руководство по работе с Rest API}}


{{Licensing}}
{{Licensing}}
Строка 7: Строка 7:
(работа с определениями БП, БП, задачами, пользователями, отношениями, логами и т.д.).
(работа с определениями БП, БП, задачами, пользователями, отношениями, логами и т.д.).


OpenApi спецификация находится <a href="https://github.com/processtech/runawfe-free-server/blob/master/wfe-restapi-client/src/main/resources/api-docs.json">тут</a>,
OpenApi спецификация находится [https://github.com/processtech/runawfe-free-server/blob/master/wfe-restapi-client/src/main/resources/api-docs.json тут],


исходный код - <a href="https://github.com/processtech/runawfe-free-server/tree/master/wfe-restapi/src/main/java/ru/runa/wfe/rest/impl">тут</a>.
исходный код - [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 (подробнее - <a href="#auth">в отдельном блоке</a>).
Авторизация - путем передачи данных (зачастую логина и пароля) в соответствующие методы и получения 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)


== {{Title|examples|Примеры}} ==
Отвечает за работу с экземплярами БП, основные методы:
* <b>/start</b> - запуск БП по названию (последней доступной версии определения)
* <b>/{definitionId}/start</b> - запуск БП по id определения
* <b>/list</b> - получение экземпляров БП по заданному фильтру
* <b>/{id}</b> - получение экземпляра БП по id


=== {{Title|java_examples|Java}} ===
== {{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|java_examples|Java}} ==
В примерах ниже для удобства будут использоваться
В примерах ниже для удобства будут использоваться
* Jackson (для сериализации в JSON),  
* Jackson (для сериализации в JSON),  
Строка 60: Строка 77:
         &lt;/dependency&gt;
         &lt;/dependency&gt;
         </pre>
         </pre>
=== {{Title|java_auth|Авторизация по логину и паролю}} ===
<pre>
        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
            }
            </pre>
=== {{Title|java_deploy_definition|Загрузка нового определения БП}} ===
<pre>
        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
            }
            </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_auth|Авторизация по логину и паролю}} ===
            <pre>
            curl -X POST "http://localhost/restapi/auth/basic" \
                -H "Content-Type: application/json" \
                -d '{"login":"Administrator", "password":"wf"}'
            </pre>
=== {{Title|curl_deploy_definition|Загрузка нового определения БП}} ===
            <pre>
            curl -X PUT "http://localhost/restapi/definition/" \
                -H "Content-Type: multipart/form-data" \
                -H "Authorization: Bearer ${jwt}" \
                -F "categories=" \
                --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>

Текущая версия на 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 '{}'