Chapter 14. REST API
Table of Contents
- Repository（倉庫）
-
- Get Deployments（獲取部署）
- Get Deployment Resource（獲取部署資源）
- Delete Deployment（刪除一個部署）
- Delete Deployments（刪除多個部署）
- Engine（引擎）
-
- Get Process Engine（獲取流程引擎）
- Processes（流程）
-
- List Process Definitions（列出多個流程定義）
- Get Process Definition（獲取流程定義）
- Get Process Definition Form（獲取流程定義的格式）
- Start Process Instance（啟動流程實例）
- Tasks（任務）
-
- Get Task Summary（獲取任務概要）
- List Tasks（列出多個任務）
- Get Task（獲取一個任務）
- Get Task Form（獲取任務格式）
- Perform Task Operation（執行任務操作）
- Identity（身份認證）
-
- Login（登錄）
- Get User（獲取一個用戶）
- List User's Groups（列表用戶所在的組）
- Get Group（獲取用戶組）
- List Group Users（列表多個組用戶）
- Management（管理）
-
- List Jobs（列出多個作業）
- Get Job（獲取一個作業）
- Execute Job（執行一個作業）
- Execute Jobs（執行多個作業）
- List Database Tables（列表顯示數據庫表）
- Get Table Meta Data（獲取庫表元數據）
- Get Table Data（獲取庫表數據）
<EXPERIMENTAL> ... the whole REST interface is still experimental
<EXPERIMENTAL> ...整個REST接口仍處于實驗性階段。
Activiti includes a REST API to the engine that will be deployed to your server when you run the setup script. The REST API uses JSON format (http://www.json.org) and is built upon the Spring Webscripts (http://www.springsurf.org).
當你運行setup腳本時，Activiti包括了可以部署到服務器上的引擎REST API。REST API使用JSON格式（http://www.json.org）并在Spring Webscripts（(http://www.springsurf.org）上構建。
It is possible to browse the REST API if you point your browser to http://localhost:8080/activiti-rest/service/index and login as one of the admin users (kermit). If you click the "Browse by Web Script Package" link you will get an overview of the packages that are deployed on the server and you can easily navigate into a package to see the REST API calls that are defined for that package. The "Alfresco JavaScript Debugger" can be ignored since Java is used instead of JavaScript to implement the logic.
如果你把瀏覽器指向http://localhost:8080/activiti-rest/service/index 并登錄為一個管理員用戶（kermi），可能瀏覽REST API。如果你點擊“Browse by Web Script Package“連接，你將得到那些部署到服務器山包的概要，你能夠輕易地瀏覽定義在那個包的REST API調用。因為使用Java替代Javascript實現這個邏輯，所以能夠忽略 "Alfresco JavaScript Debugger" 。
Each REST API call has its individual authorization level and you must be logged in as a user to invoke a REST API call (except for the /login service). Authentication is done using Basic HTTP Authentication, so if you logged in as an admin (i.e. kermit) to browse the REST API, as described above, you should be able to perform all calls as described below.
每個REST API調用具有它單個的認證級別，為了調用REST API方法，你必須一個用戶登錄（除了/login服務）。因為使用基本的HTTP認證（ Basic HTTP Authentication）來完成，所以如果你以一個管理員登錄（例如kermit）可以瀏覽以上的REST API，那么你應當能夠完成如下的所有的調用。
The API follows normal REST API conventions using GET for read operations, POST for creating objects, PUT for updating and performing operations on already created objects and finally DELETE for deleting objects. When performing a call that affects multiple objects POST is used on all such operations for consistency and making sure that an unlimited number of objects may be used. The reason for using POST is that the HTTP DELETE method doesn't implicitly allow request bodies and therefore, a call using DELETE, in theory, could get it's request body stripped out by a proxy. So to be certain this doesn't happen we use POST, even when PUT could have been used to update multiple objects, for consistency.
API遵從通常的REST API約定：用GET讀取操作，用POST建立對象，用PUT在已經建立的對象上更新和執行操作，最后用DELETE刪除對象。為了一致性，并且可以使用無限的對象，當執行影響多個對象的調用時，使用POST。使用POST的原因，是HTTP DELETE方法不允許顯式使用請求包體。理論上使用DELETE的調用可能得到被代理裁剪的請求包體。所以，在某種程度上，我們使用POST就不會發生這種情況。甚至當當可能使用PUT來更新多個對象時，為了保證一致性，也采用POST。
The base URL for invoking a REST call is http://localhost:8080/activiti-rest/service/. So for example to list the process definitions in the engine point your browser to: http://localhost:8080/activiti-rest/service/process-engine
調用REST方法的基本URL是http://localhost:8080/activiti-rest/service/。所以，為了列出引擎里面的流程定義，請將瀏覽器指向：http://localhost:8080/activiti-rest/service/process-engine
Please look below to see what REST API calls that currently are available. Please consider the "API" sections as a "one line hint" to what functionality of the core API that is used to implement the REST API call.
請查看下面的當前可獲得的REST API調用。請參考"API"部分作為對core API具有的功能性的“一行提示（one line hint)"。核心API用來實現REST API 調用。
Repository（倉庫）
Get Deployments（獲取部署）
Returns a paginated list deployments that can be sorted by "id", "name" or "deploymentTime".
返回可以以分頁列表顯示的部署。部署能夠以"id", "name"或 or "deploymentTime"排序
-
Request: GET /deployments?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepositoryService().createDeploymentQuery().listPage()
-
Response:
{
"data": [
{
"id": "10",
"name": "activiti-examples.bar",
"deploymentTime": "2010-10-13T14:54:26.750+02:00"
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Get Deployment Resource（獲取部署資源）
Returns a resource from the deployment. Example: /deployment/10/resource/org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml
從部署獲取資源。例如：/deployment/10/resource/org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml
-
Request: GET /deployment/{deploymentId}/resource/{resourceName}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepositoryService().getResourceAsStream(deploymentId, resourceName)
-
Response:
I.e a .bpmn20.xml file, an image or whatever type of file the deployment resource contained.
Delete Deployment（刪除一個部署）
Deletes a deployment.
刪除一個部署.
Delete Deployments（刪除多個部署）
Deletes multiple deployment.
刪除多個部署。
-
Request: POST /deployments?cascade={cascade?}
{
"deploymentIds": [ "10", "11" ]
}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepositoryService().deleteDeployment(deploymentId)
-
Response:
{
"success": true
}
Engine（引擎）
Get Process Engine（獲取流程引擎）
Returns the process engine initialization details. If something went wrong during startup, details about the error will be given in the "exception" attribute in the response.
返回流程引擎初始化過程的細節。如果在啟動階段有錯，細節將顯示在響應里面的"異常"屬性。
-
Request: GET /process-engine
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName)
-
Response:
{
"name": "default",
"resourceUrl": "jar:file:\//<path-to-deployment>\/activiti-cfg.jar!\/activiti.properties",
"exception": null,
"version": "5.0-SNAPSHOT"
}
Processes（流程）
List Process Definitions（列出多個流程定義）
Returns details about the deployed process definitions that can be sorted by "id", "name", "version" or "deploymentTime". The name of the BPMN2.0 XML process diagram is given in the "resourceName" attribute and can, in combination with the "deploymentId" attribute, be retrieved from the GET Deployment Resource REST API call above. If the process has a start form it is given in the "startFormResourceKey" attribute. The start form for a process can be retrieved from the GET Start Process Form REST API call.
返回有關已部署流程定義的細節。流程定義能夠按"id", "name", "version" 或 "deploymentTime"排序。和“deploymentId"屬性組合，在“resourceName"屬性給定的BPMN 2.0 XML流程圖的名稱能夠從GET Deployment Resource REST API 。以上的調用檢索出來。一個流程的開始格式能夠從GET Start Process Form REST Form REST API 調用檢索出來。
-
Paginated Request: GET /process-definitions?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getProcessService().findProcessDefinitions()
-
Paginated Response:
{
"data": [
{
"id": "financialReport:1",
"key": "financialReport",
"version": 1,
"name": "Monthly financial report",
"resourceName": "org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml",
"deploymentId": "10",
"startFormResourceKey": null
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Get Process Definition（獲取流程定義）
Returns details about a deployed process definition.
獲取一個已部署流程定義的細節。
-
Request: GET /process-definition/{processDefinitionId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getProcessService().findProcessDefinitionById(processDefinitionId)
-
Response:
{
"id": "financialReport:1",
"key": "financialReport",
"version": 1,
"name": "Monthly financial report",
"resourceName": "org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml",
"deploymentId": "10",
"startFormResourceKey": null
}
Get Process Definition Form（獲取流程定義的格式）
Returns a process definition's form.
返回一個流程定義的格式。
-
Request: GET /process-definition/{processDefinitionId}/form[?format=html|json]
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskService().getRenderedStartFormById(processDefinitionId)
-
Response:
<user-defined-response>
Start Process Instance（啟動流程實例）
Creates a process instance based on a process definition and returns details about the newly created process instance. Additional variables (from a form) may be passed using the body object. In other words placing attributes next to the "processDefinitionId" attribute.
創建一個基于流程定義的流程實例并返回新創建的流程實例的細節。通過body對象可以傳送額外的變量（來自表單）。換句話說，將屬性放置到"processDefinitionId"屬性之后。
These additional variables may also be described using "meta data fields". A variable named "numberOfDays" with value "2" may be described as an int using an extra variable named "numberOfDays_type" set to "Integer" and to describe it as a required variable use an extra variable named "numberOfDays_required" set to "true". If no type descriptor is used the value will be treated as a String as long as its surrounded by '"'-characters. Its also possible to set the type to "Boolean".
這些額外的變量也可以使用"meta data fields"來描述。帶有值為”2“的名為"numberOfDays"的變量可以描述為int。使用額外的名叫numberOfDays_type的變量設置為”Integer“。使用額外的設置為”true“的名叫”numberOfDays_required“的變量來作為需要的變量來描述。如果沒有類型，一旦用""字符包圍，在值里面使用的描述符將以字符串對待。
Note that if a value is submitted as true (instead of "true") it will be treated as a Boolean even if no descriptor is used. The same is also valid for number, i.e., 123 will become an Integer but "123" will become a String (unless a descriptor is defined). Note that no variables containing "_" in the name will be saved, they are only treated as meta data fields.
注意如果以true提交（代替"true"），甚至沒有使用描述符，它將以Boolen值對待。同樣對數值也一樣，例如123將成為一個Integer，而”123“將成為字符串（除非定義一個描述符）。注意在名稱里面包含"_" 的變量將不被保存，它們只是作為元數據的字段。
The reason for using these meta data fields is to make it possible using a standard HTML form to submit the values (since an HTML form submits everything as strings its not possible to distinguish the type of a value as in JSON). HTML submission will be supported in the near future. It is of course not an optimal solution to let the client send instructions to the server about which variables that are required and what type they have, but this is a temporary solution to enable simple form handling. We are currently looking for more proper solutions for forms, containing real meta models that can be used on the server to avoid using meta data fields like above. I.e. X-forms or Alfresco Forms. Please feel free to give suggestions or tips in the Activiti Forum.
使用這些元數據字段的理由是使得采用標準的HTML表單來提交這些值成為可能（因為HTML表單以字符串方式提交任何類型，而在JSON里面區分值類型是不可能的）。在不遠的將來將支持HTML提交。當然，盡管讓客戶將有關需要那個變量及其類型的指令發送到服務器并不是優選，但是這是讓簡單表單處理的臨時方案。我們現在正在尋找表單更合適的解決方案，包括為了避免使用上述元數據字段而在服務器端使用的真實的元模型。例如，X-forms 或者 Alfresco Forms.請在Activiti論壇上自由發表建議和提示。
-
Request: POST /process-instance
{
"processDefinitionId":"financialReport:1"
}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getProcessService().startProcessInstanceById(processDefinitionId[, variables])
-
Response:
{
"id": "217",
"processDefinitionId": "financialReport:1",
"activityNames": ["writeReportTask"],
"ended": true
}
Tasks（任務）
Get Task Summary（獲取任務概要）
Returns a task summary for a specific user: The number of tasks assigned the user, how many unassigned tasks that the user may claim and how many unassigned tasks there are per group that the user is a member of.
返回某一用戶的任務概要：分配給用戶的任務數目，用戶可以領取的未分配任務的數目，以及用戶所在每個組具有的未分配的任務數目。
-
Request: GET /tasks-summary?user={userId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskService().createTaskQuery().xxx().count()
-
Response:
{
"assigned": {
"total": 0
},
"unassigned": {
"total": 1,
"groups":
{
"accountancy": 1,
"sales": 0,
"engineering": 0,
"management": 0
}
}
}
List Tasks（列出多個任務）
Returns a paginated list of tasks that can be sorted by: "id", "name", "description", "priority", "assignee", "executionId" or "processInstanceId". The list must be based on a user of a specific role: assignee (lists the tasks assigned to the user) or candidate (lists the tasks that the user may claim) or a candidate group (lists tasks that the members of the group may claim). If the task has a form it is given in the "formResourceKey" attribute. The form for a task can be retrieved from the GET Task Form REST API call.
返回能夠按"id", "name", "description", "priority", "assignee", "executionId" 或 "processInstanceId"排序的多個任務的分頁列表。這個列表必須基于某個角色的用戶：受托人（列出分配給用戶的任務）或者候選人（列出用戶可以領取的任務）或者候選人組（列出組成員可以領取任務）。如果這個任務有一個表單，在"formResourceKey" 屬性里給出。任務表單可以從 GET Task Form REST API調用中檢索。
-
Paginated Request: GET /tasks?[assignee={userId}|candidate={userId}|candidate-group={groupId}]&start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskService().createTaskQuery().xxx().listPage()
-
Paginated Response:
{
"data": [
{
"id": 127,
"name": "Handle vacation request",
"description": "Vacation request by Kermit",
"priority": 50,
"assignee": null,
"executionId": 118,
"formResourceKey": "org/activiti/examples/taskforms/approve.form"
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Get Task（獲取一個任務）
Returns details about the task with the task id
. 返回帶有task id的任務有關的細節。
-
Request: GET /task/{taskId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskService().findTask(taskId)
-
Response:
{
"id": 127,
"name": "Handle vacation request",
"description": "Vacation request by Kermit",
"priority": 50,
"assignee": null,
"executionId": 118,
"formResourceKey": "org/activiti/examples/taskforms/approve.form"
}
Get Task Form（獲取任務格式）
Returns a task's form.
返回一個任務的格式。
Perform Task Operation（執行任務操作）
Performs an operation (claim or complete) on a task. For the "complete" operation additional variables (from a form) may be passed in the body. To read more about additional variables from forms, visit the Start Process Instance section
在任務上執行操作（領取或者完成）。針對“完成“操作，可以在包體里面傳送的額外的變量(來自格式)。為了讀取來自格式里面的額外變量，訪問“啟動流程示例（ Start Process Instance）部分。
Identity（身份認證）
Login（登錄）
Authenticates a user. If user and password doesn't match a response with status 403 is returned. If authentication is successful, a response with status 200 is returned.
認證一個用戶。如果用戶和密碼不一致，返回一個狀態為403的響應。如果認證成功，返回一個狀態為200的狀態。
-
Request: POST /login
{
"userId": "kermit",
"password": "kermit"
}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentityService().checkPassword(userId, password)
-
Response:
{
"success": true
}
Get User（獲取一個用戶）
Returns details about a user.
返回有關一個用戶的細節。
-
Request: GET /user/{userId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentityService().findUser(userId)
-
Response:
{
"id": "kermit",
"firstName": "Kermit",
"lastName": "the Frog",
"email": "kermit@server.com"
}
List User's Groups（列表用戶所在的組）
Returns a paginated list groups belonging to a user that can be sort by "id", "name" or "type". To only get groups of a certain type use the "type" parameter.
返回屬于一個用戶的可分頁列表的組。用戶能夠按 "id", "name" 或or "type"排序。只獲取某一類型的組，使用“type“參數。
-
Paginated Request: GET /user/{userId}/groups[?type=groupType]?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentityService().xxx(userId[, groupType])
-
Paginated Response:
{
data: [
{
"id": "admin",
"name": "System administrator",
"type": "security-role"
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Get Group（獲取用戶組）
Returns details about a group.
返回有關組的細節。
-
Request: GET /group/{groupId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentityService().findGroup(groupId)
-
Response:
{
"id": "admin",
"name": "System administrator",
"type": "security-role"
}
List Group Users（列表多個組用戶）
Returns details about a group's users that can be sorted by "id", "firstName", "lastName" or "email".
返回有關能夠按 "id", "firstName", "lastName"或者 "email"排序的組用戶的細節。
-
Paginated Request: GET /groups/{groupId}/users
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentityService().findUsersByGroup(userId)
-
Paginated Response:
{
data: [
{
"id": "kermit",
"firstName": "Kermit",
"lastName": "the Frog",
"email": "kermit@server.com"
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Management（管理）
List Jobs（列出多個作業）
Returns a paginated list of jobs that can be sorted by "id", "process-instance-id", "execution-id", "due-date", "retries" or some custom arbitrary property id. The list can also be filtered by process instance id, due date or if the jobs have retries, are executable or only have messages or timers.
返回多個作業的分頁列表：可以按"id", "process-instance-id", "execution-id", "due-date", "retries" 或者一下定制的屬性id排序。這個列表也能夠按process instance id, due date進行過濾。列表是可執行的或者只具有消息或者定時器。
-
Paginated Request: GET /management/jobs?process-instance={processInstanceId?}&with-retries-left={withRetriesLeft=false}&executable={axecutable=false}&only-timers={onlyTimers=false}&only-messages={onlyMessage=false}&duedate-lt={iso8601Date}&duedate-ltoe={iso8601Date}&duedate-ht={iso8601Date}&duedate-htoe={iso8601Date}&start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).createJobQuery().xxx().listPage()
-
Paginated Response:
{
"data": [
{
"id": "212",
"executionId": "211",
"retries": -1,
"processInstanceId": "210",
"dueDate": null,
"assignee": null,
"exceptionMessage": "Can\'t find scripting engine for \'groovy\'"
}
],
"total": 1,
"start": 0,
"sort": "id",
"order": "asc",
"size": 1
}
Get Job（獲取一個作業）
Returns details about a job.
返回一個作業有關的細節。
-
Request: GET /management/job({jobId}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).createJobQuery().id(jobId).singleResult()
-
Response:
{
"id": "212",
"executionId": "211",
"retries": -1,
"processInstanceId": "210",
"dueDate": null,
"assignee": null,
"exceptionMessage": "Can\'t find scripting engine for \'groovy\'",
"stacktrace": "org.activiti.engine.ActivitiException: Can't find scripting engine for 'groovy'\n\tat ..."
}
Execute Job（執行一個作業）
Executes a job.
執行一個作業。
Execute Jobs（執行多個作業）
Executes multiple job.
執行多個作業。
List Database Tables（列表顯示數據庫表）
Returns meta data information about all database tables in the engine.
返回有關引擎里面所有數據庫表的元數據信息。
-
Request: GET /management/tables
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagementService().getTableCount()
-
Response:
{
"data": [
{
"tableName": "ACT_GE_PROPERTY",
"noOfResults": 2
}
]
}
Get Table Meta Data（獲取庫表元數據）
Returns meta data about a database table.
返回有關數據庫表的元數據。
-
Request: GET /management/table/{tableName}
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagementService().getTableMetaData(tableName))
-
Response:
{
"tableName": "ACT_GE_PROPERTY",
"columnNames": ["REV_","NAME_","VALUE_"],
"columnNames": ["class java.lang.Integer", "class java.lang.String", "class java.lang.String"]
}
Get Table Data（獲取庫表數據）
Returns a paginated list of database table data.
返回數據庫表數據的分頁列表。
-
Paginated Request: GET /management/table/{tableName}/data
-
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagementService().createTablePageQuery().tableName(tableName).start(start).size(size).orderXXX(sort).singleResult();
-
Paginated Response:
{
"data": [
{
"NAME_": "schema.version",
"REV_": "1",
"VALUE_": "5.0-SNAPSHOT"
},
{
"NAME_": "next.dbid",
"REV_": "4",
"VALUE_": "310"
}
],
"total": 2,
"start": 0,
"sort": "NAME_",
"order": "asc",
"size": 2
}
The whole REST interface is still experimental ... </EXPERIMENTAL>
整個REST接口仍處于實驗階段 ... </EXPERIMENTAL>