REST API

Doubao 中英对照 REST API

Flowable REST 通用原则

安装与认证

Flowable 包含一个面向 Flowable 引擎的 REST API，可通过将 flowable-rest.war 文件部署到 Apache Tomcat 之类的 servlet 容器中来安装。此外，也可以在另一个 web 应用中使用它，方法是在你的应用中包含该 servlet（和/或其映射），并将所有 flowable-rest 依赖添加到 classpath。

默认情况下，Flowable 引擎会连接到内存中的 H2 数据库。你可以在 WEB-INF/META-INF/flowable-app 文件夹下的 flowable-app.properties 文件中更改数据库设置。REST API 使用 JSON 格式（http://www.json.org），并构建在 Spring MVC（http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html）之上。

默认情况下，所有 REST 资源都要求一个具有 rest-access-api 权限的有效用户通过认证。如果希望任何有效用户都能调用 REST API，可以将 flowable.rest.app.authentication-mode 设置为 any-user（在旧版本 Flowable 中这是默认值）。

可以通过设置以下属性来配置一个能够访问 REST API 的默认用户：

flowable.rest.app.admin.user-id=rest-admin
flowable.rest.app.admin.password=test
flowable.rest.app.admin.first-name=Rest
flowable.rest.app.admin.last-name=Admin

REST 应用启动时，如果该用户不存在则创建它，否则获取它。该用户将被授予 access-rest-api 权限，默认访问 REST API 需要此权限。之后请勿忘记更改该用户的密码。如果未设置 flowable.rest.app.admin.user-id，则不会创建任何用户或权限。因此，在初始设置完成后，移除该属性并不会移除之前已配置的用户或权限。

使用基本 HTTP 访问认证，因此在执行请求时，你应始终包含一个 Authorization: Basic …== HTTP 头，或在请求 URL 中包含用户名和密码（例如 *http://username:password@localhost:8080/xyz*）。

我们建议你将基本认证与 HTTPS 结合使用。

配置

Flowable REST web 应用使用 Spring Java Configuration 来启动 Flowable Form 引擎，使用 Spring security 定义基本认证安全性，并定义用于特定变量处理的变量转换器。
通过修改 flowable-app.properties 文件可以定义少量属性，该文件位于 WEB-INF/META-INF/flowable-app/flowable-app.properties 文件夹。
如果需要更高级的配置选项，可以在 WEB-INF/classes 文件夹下的 flowable-custom-context.xml 文件中覆盖默认的 Spring bean（XML 方式）。
该文件中已以注释形式给出了一个示例配置。这里也是覆盖默认 RestResponseFactory 的地方，方法是定义一个名为 restResponsefactory 的新 Spring bean，并为其使用你自定义的实现类。

在 Tomcat 中使用

由于 Tomcat 的默认安全属性，默认不允许转义的正斜杠（%2F 和 %5C）（会返回 400 结果）。这可能会影响部署资源及其 data-URL，因为该 URL 可能包含转义的正斜杠。

当遇到意外的 400 结果问题时，设置以下系统属性：

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

对于下文所述的 HTTP 请求，最佳实践是始终将 Accept 和 Content-Type（在 POST/PUT JSON 的情况下）头设置为 application/json。

方法与返回码

HTTP 方法与对应操作

方法	操作
GET	获取单个资源或获取资源集合。
POST	创建新资源。也用于执行请求结构过于复杂、无法放入 GET 请求查询 URL 的资源查询。
PUT	更新已有资源的属性。也用于对已有资源调用操作。
DELETE	删除已有资源。

HTTP 方法响应码

响应	描述
200 - Ok	操作成功，并已返回响应（GET 和 PUT 请求）。
201 - Created	操作成功，实体已创建并在响应体中返回（POST 请求）。
204 - No content	操作成功，实体已删除，因此不返回响应体（DELETE 请求）。
401 - Unauthorized	操作失败。该操作要求设置 Authentication 头。如果请求中已包含该头，则提供的凭据无效，或用户无权执行此操作。
403 - Forbidden	该操作被禁止，不应重试。这意味着是授权问题而非认证问题，即该操作不被允许。例如：删除属于正在运行流程的任务是不允许的，并且无论用户或流程/任务状态如何，都永远不允许。
404 - Not found	操作失败。未找到请求的资源。
405 - Method not allowed	操作失败。该方法不允许用于此资源。例如，尝试更新（PUT）一个部署资源将导致 405 状态。
409 - Conflict	操作失败。该操作导致对某资源的更新，而该资源已被另一操作更新，使得本次更新不再有效。也可能表示正在一个集合中创建资源，而该集合中已存在具有该标识符的资源。
415 - Unsupported Media Type	操作失败。请求体包含不支持的媒体类型。当请求体 JSON 包含无法转换的不支持内容类型时也会出现。

除非请求的是二进制内容（例如部署资源数据），否则 HTTP 响应的媒体类型始终为 application/json；此时使用该内容自身的媒体类型。

错误响应体

发生错误时（客户端和服务端均包括，即 4XX 和 5XX 状态码），响应体包含一个描述所发生错误的对象。下面是任务未找到时 404 状态的示例：

{
  "statusCode" : 404,
  "errorMessage" : "Could not find a task with id '444'."
}

请求参数

URL 片段

作为 URL 一部分的参数（例如 http://host/flowable-rest/process-api/repository/deployments/\{deploymentId} 中的 deploymentId 参数）需要被正确转义（参见 URL 编码或百分号编码）。

Rest URL 查询参数

作为查询字符串添加到 URL 中的参数（例如 http://host/flowable-rest/process-api/repository/deployments?name=Deployment 中使用的 name 参数）可以具有以下类型，并在相应的 REST API 文档中说明：

URL 查询参数类型

类型	格式
String	纯文本参数。可包含 URL 中允许的任何有效字符。对于 XXXLike 参数，字符串应包含通配符 %（需正确进行 URL 编码）。这使你可以指定 like 搜索的意图。例如，'Tas%' 匹配所有以 'Tas' 开头的值。
Integer	表示整数值的参数。只能包含数值型非小数，介于 -2.147.483.648 和 2.147.483.647 之间。
Long	表示 long 值的参数。只能包含数值型非小数，介于 -9.223.372.036.854.775.808 和 9.223.372.036.854.775.807 之间。
Boolean	表示布尔值的参数。可以为 true 或 false。除此之外的所有其他值都会导致 '405 - Bad request' 响应。
Date	表示日期值的参数。使用 ISO-8601 日期格式（参见维基百科上的 ISO-8601），同时使用时间和日期组件（例如 2013-04-03T23:45Z）。

JSON 请求体参数

JSON 参数类型

类型	格式
String	纯文本参数。对于 XXXLike 参数，字符串应包含通配符 %。这使你可以指定 like 搜索的意图。例如，'Tas%' 匹配所有以 'Tas' 开头的值。
Integer	表示整数值的参数，使用 JSON 数字。只能包含数值型非小数，介于 -2.147.483.648 和 2.147.483.647 之间。
Long	表示 long 值的参数，使用 JSON 数字。只能包含数值型非小数，介于 -9.223.372.036.854.775.808 和 9.223.372.036.854.775.807 之间。
Date	表示日期值的参数，使用 JSON 文本。使用 ISO-8601 日期格式（参见维基百科上的 ISO-8601），同时使用时间和日期组件（例如 2013-04-03T23:45Z）。

分页与排序

分页和排序参数可以作为查询字符串添加到 URL 中（例如 http://host/flowable-rest/process-api/repository/deployments?sort=name 中使用的 name 参数）。

变量查询 JSON 参数

参数	默认值	描述
sort	因查询实现而异	排序键的名称，其默认值和允许值因查询实现而异。
order	asc	排序顺序，可以为 'asc' 或 'desc'。
start	0	允许对结果分页的参数。默认结果从 0 开始。
size	10	允许对结果分页的参数。默认大小为 10。

注意

请记住，start 参数用作查询的偏移量。例如，要分三页、每页三项（共 9 项）获取任务，我们会使用：

GET /runtime/tasks?start=0&size=3
GET /runtime/tasks?start=3&size=3
GET /runtime/tasks?start=6&size=3

JSON 查询变量格式

{
  "name" : "variableName",
  "value" : "variableValue",
  "operation" : "equals",
  "type" : "string"
}

变量查询 JSON 参数

参数	是否必需	描述
name	否	要包含在查询中的变量名。在某些查询中使用 'equals' 查询具有给定值的任意变量名的资源时，该参数可以为空。
value	是	查询中包含的变量值，应包含给定类型的正确格式。
operator	是	查询中使用的操作符，可以取以下值：equals、notEquals、equalsIgnoreCase、notEqualsIgnoreCase、lessThan、greaterThan、lessThanOrEquals、greaterThanOrEquals 和 like。
type	否	要使用的变量类型。省略时，类型将从 value 参数推断。任何 JSON 文本值将被视为 string 类型，JSON 布尔值为 boolean 类型，JSON 数字根据数字大小为 long 或 integer 类型。建议在不确定时显式指定类型。开箱即用支持的类型列于下表。

默认查询 JSON 类型

类型名	描述
string	值被视为并转换为 java.lang.String。
short	值被视为并转换为 java.lang.Integer。
integer	值被视为并转换为 java.lang.Integer。
long	值被视为并转换为 java.lang.Long。
double	值被视为并转换为 java.lang.Double。
boolean	值被视为并转换为 java.lang.Boolean。
date	值被视为并转换为 java.util.Date。JSON 字符串将使用 ISO-8601 日期格式转换。

变量表示

处理变量（执行决策）时，REST API 对读取和写入都使用一些通用原则和 JSON 格式。变量的 JSON 表示如下所示：

{
  "name" : "variableName",
  "value" : "variableValue",
  "valueUrl" : "http://...",
  "type" : "string"
}

变量 JSON 属性

参数	是否必需	描述
name	是	变量名。
value	否	变量值。写入变量时如果省略 value，将使用 null 作为值。
valueUrl	否	读取 binary 或 serializable 类型的变量时，该属性指向可获取原始二进制数据的 URL。
type	否	变量类型。有关类型的更多信息见下表。写入变量时如果省略此值，类型将从原始 JSON 属性请求类型推断，且仅限于 string、double、integer 和 boolean。建议始终包含 type，以确保不会对类型做出错误假设。

变量类型

类型名	描述
string	值被视为 java.lang.String。写入变量时使用原始 JSON 文本值。
integer	值被视为 java.lang.Integer。写入时以 JSON 数字值作为转换基础，回退到 JSON 文本。
short	值被视为 java.lang.Short。写入时以 JSON 数字值作为转换基础，回退到 JSON 文本。
long	值被视为 java.lang.Long。写入时以 JSON 数字值作为转换基础，回退到 JSON 文本。
double	值被视为 java.lang.Double。写入时以 JSON 数字值作为转换基础，回退到 JSON 文本。
boolean	值被视为 java.lang.Boolean。写入时使用 JSON 布尔值进行转换。
date	值被视为 java.util.Date。写入时，JSON 文本将使用 ISO-8601 日期格式转换。

可以使用自定义 JSON 表示（简单值或复杂/嵌套 JSON 对象）来支持额外的变量类型。通过扩展 org.flowable.dmn.rest.service.api.DmnRestResponseFactory 上的 initializeVariableConverters() 方法，你可以添加额外的 org.flowable.rest.variable.RestVariableConverter 类，以支持将你的 POJO 转换为适合通过 REST 传输的格式，并将 REST 值转换回你的 POJO。实际到 JSON 的转换由 Jackson 完成。

部署

使用 Tomcat 时，请阅读在 Tomcat 中使用。

DMN 部署列表

GET dmn-repository/deployments

URL 查询参数

参数	是否必需	值	描述
name	否	String	仅返回具有给定名称的部署。
nameLike	否	String	仅返回名称类似于给定名称的部署。
category	否	String	仅返回具有给定类别的部署。
categoryNotEquals	否	String	仅返回不具有给定类别的部署。
tenantId	否	String	仅返回具有给定 tenantId 的部署。
tenantIdLike	否	String	仅返回 tenantId 类似于给定值的部署。
withoutTenantId	否	Boolean	如果为 true，仅返回未设置 tenantId 的部署。如果为 false，忽略 withoutTenantId 参数。
sort	否	'id'（默认）、'name'、'deploytime' 或 'tenantId'	排序属性，与 'order' 一起使用。

REST 响应码

响应码	描述
200	表示请求成功。

成功响应体：

{
  "data": [
    {
      "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
      "name": null,
      "deploymentTime": "2016-12-14T10:16:37.000+01:00",
      "category": null,
      "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
      "parentDeploymentId": "17510",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "id",
  "order": "asc",
  "size": 1
}

获取 DMN 部署

GET dmn-repository/deployments/{deploymentId}

获取部署 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	要获取的部署的标识符。

获取部署 - 响应码

响应码	描述
200	表示已找到并返回该部署。
404	表示未找到请求的部署。

成功响应体：

{
  "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "name": null,
  "deploymentTime": "2016-12-14T10:16:37.000+01:00",
  "category": null,
  "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "parentDeploymentId": "17510",
  "tenantId": ""
}

创建新的 DMN 部署

POST dmn-repository/deployments

请求体：

请求体应包含 multipart/form-data 类型的数据。请求中应恰好有一个文件；任何额外文件都将被忽略。部署名称即为传入的文件字段的名称。

可以在请求体中传入一个名为 tenantId 的额外参数（表单字段）。该字段的值将用作本次部署所属租户的标识符。

创建新的 DMN 部署 - 响应码

响应码	描述
201	表示部署已创建。
400	表示请求体中没有内容，或内容的 mime 类型不支持部署。状态描述包含更多信息。

成功响应体：

{
  "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "name": "newDeployment1",
  "deploymentTime": "2016-12-14T10:16:37.000+01:00",
  "category": null,
  "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "tenantId" : "myTenant"
}

删除 DMN 部署

DELETE dmn-repository/deployments/{deploymentId}

删除 DMN 部署 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	要删除的部署的标识符。

删除 DMN 部署 - 响应码

响应码	描述
204	表示已找到部署并已删除。响应体有意为空。
404	表示未找到请求的部署。

获取 DMN 部署资源内容

GET dmn-repository/deployments/{deploymentId}/resourcedata/{resourceId}

获取部署资源内容 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	请求资源所属部署的标识符。
resourceId	是	String	要获取数据的资源的标识符。如果 resourceId 包含正斜杠，请务必对其进行 URL 编码。例如，使用 'decisions%2Fmy-decision.dmn' 而非 'decisions/my-decision.dmn'。

获取部署资源内容 - 响应码

响应码	描述
200	表示部署和资源均已找到，并已返回资源数据。
404	表示未找到请求的部署，或部署中不存在具有给定标识符的资源。状态描述包含更多信息。

成功响应体：

响应体将包含请求资源的二进制资源内容。响应 content-type 将与资源 'mimeType' 属性中返回的类型相同。此外，还会设置 content-disposition 头，使浏览器下载该文件而非显示它。

决策表

决策表列表

GET dmn-repository/decision-tables

流程定义列表 - URL 参数

参数	是否必需	值	描述
version	否	integer	仅返回具有给定版本的流程定义。
name	否	String	仅返回具有给定名称的流程定义。
nameLike	否	String	仅返回名称类似于给定名称的流程定义。
key	否	String	仅返回具有给定 key 的流程定义。
keyLike	否	String	仅返回 key 类似于给定 key 的流程定义。
resourceName	否	String	仅返回具有给定资源名的流程定义。
resourceNameLike	否	String	仅返回资源名类似于给定名称的流程定义。
category	否	String	仅返回具有给定类别的流程定义。
categoryLike	否	String	仅返回类别类似于给定名称的流程定义。
categoryNotEquals	否	String	仅返回不具有给定类别的流程定义。
deploymentId	否	String	仅返回属于具有给定标识符的部署的流程定义。
latest	否	Boolean	仅返回最新的流程定义版本。只能与 'key' 和 'keyLike' 参数一起使用，使用任何其他参数将导致 400 响应。
sort	否	'name'（默认）、'id'、'key'、'category'、'deploymentId' 和 'version'	排序属性，与 'order' 一起使用。

流程定义列表 - 响应码

响应码	描述
200	表示请求成功，并返回决策表
400	表示传入的参数格式错误，或 'latest' 与 'key' 和 'keyLike' 以外的参数一起使用。状态消息包含更多信息。

成功响应体：

{
  "data": [
        {
      "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-repository/decision-tables/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "category": null,
      "name": "Decision Table One",
      "key": "DecisionTableOne",
      "description": null,
      "version": 3,
      "resourceName": "dmn-DecisionTableOne.dmn",
      "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
      "parentDeploymentId": "5001",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}

获取决策表

GET dmn-repository/decision-tables/{decisionTableId}

获取决策表 - URL 参数

参数	是否必需	值	描述
decisionTableId	是	String	要获取的决策表的标识符。

获取决策表 - 响应码

响应码	描述
200	表示已找到并返回该决策表。
404	表示未找到请求的决策表。

成功响应体：

{
  "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-repository/decision-tables/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "category": null,
  "name": "Decision Table One",
  "key": "DecisionTableOne",
  "description": null,
  "version": 3,
  "resourceName": "dmn-DecisionTableOne.dmn",
  "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
  "parentDeploymentId": "5001",
  "tenantId": ""
}

获取决策表资源内容

GET dmn-repository/decision-tables/{decisionTableId}/resourcedata

获取决策表资源内容 - URL 参数

参数	是否必需	值	描述
decisionTableId	是	String	要获取其资源数据的决策表的标识符。

响应：

响应码/响应体与 GET dmn-repository/deployment/{deploymentId}/resourcedata/{resourceId} 完全相同。

获取决策表 DMN 模型

GET dmn-repository/decision-tables/{decisionTableId}/model

获取决策表 DMN 模型 - URL 参数

参数	是否必需	值	描述
decisionTableId	是	String	要获取其模型的决策表的标识符。

获取决策表 DMN 模型 - 响应码

响应码	描述
200	表示已找到决策表并返回模型。
404	表示未找到请求的决策表。

响应体：
响应体是 org.flowable.dmn.model.DmnDefinition 的 JSON 表示，包含完整的 DMN 定义模型。

{
   "processes":[
      {
         "id":"oneTaskProcess",
         "xmlRowNumber":7,
         "xmlColumnNumber":60,
         "extensionElements":{

         },
         "name":"The One Task Process",
         "executable":true,
         "documentation":"One task process description",

    ]
}

DMN 规则服务

执行决策

POST dmn-rule/execute

请求体：

请求体应包含 multipart/form-data 类型的数据。decisionKey 为必填。tenantId、parentDeploymentId 以及 inputVariables（restVariables）映射为可选。

响应体：

{
  "resultVariables": [
    [
      {
        "name": "output1",
        "type": "string",
        "value": "result 1"
      }
    ],
    [
      {
        "name": "output1",
        "type": "string",
        "value": "result 2"
      }
    ],
    [
      {
        "name": "output1",
        "type": "string",
        "value": "result 3"
      }
    ]
  ],
  "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-rule/execute"
}

执行决策 - 响应码

响应码	描述
201	表示决策已执行。

执行单结果决策

POST dmn-rule/execute/single-result

请求体：

请求体应包含 multipart/form-data 类型的数据。decisionKey 为必填。tenantId、parentDeploymentId 以及 inputVariables（restVariables）映射为可选。

当多条规则有效时，服务将返回 500 状态码。
注意：带有复合输出的单命中是有效的（见下文响应）

响应体：

{
  "resultVariables": [
    {
      "name": "output1",
      "type": "string",
      "value": "compound 1"
    },
    {
      "name": "output2",
      "type": "string",
      "value": "compound 2"
    }
  ],
  "url": "http://localhost:8080/flowable-rest/dmn-api/dmn-rule/execute/single-result"
}

执行单结果决策 - 响应码

响应码	描述
201	表示决策已执行。
500	表示决策返回了多个结果。

引擎

获取 DMN 引擎信息

GET dmn-management/engine

返回此 REST 服务中所用 DMN 引擎的只读视图。

成功响应体：

{
   "name":"default",
   "version":"6.6.0",
   "resourceUrl":"file://flowable-dmn/flowable.dmn.cfg.xml",
   "exception":null
}

获取引擎信息 - 响应码

响应码	描述
200	表示已返回引擎信息。

Flowable REST 通用原则​

安装与认证​

配置​

在 Tomcat 中使用​

方法与返回码​

错误响应体​

请求参数​

URL 片段​

Rest URL 查询参数​

JSON 请求体参数​

分页与排序​

JSON 查询变量格式​

变量表示​

部署​

DMN 部署列表​

获取 DMN 部署​

创建新的 DMN 部署​

删除 DMN 部署​

获取 DMN 部署资源内容​

决策表​

决策表列表​

获取决策表​

获取决策表资源内容​

获取决策表 DMN 模型​

DMN 规则服务​

执行决策​

执行单结果决策​

引擎​

获取 DMN 引擎信息​

Flowable REST 通用原则

安装与认证

配置

在 Tomcat 中使用

方法与返回码

错误响应体

请求参数

URL 片段

Rest URL 查询参数

JSON 请求体参数

分页与排序

JSON 查询变量格式

变量表示

部署

DMN 部署列表

获取 DMN 部署

创建新的 DMN 部署

删除 DMN 部署

获取 DMN 部署资源内容

决策表

决策表列表

获取决策表

获取决策表资源内容

获取决策表 DMN 模型

DMN 规则服务

执行决策

执行单结果决策

引擎

获取 DMN 引擎信息