# RESTful Interface Description {docsify-ignore-all}
>This document provides a detailed explanation of the RESTful interface provided by the Huizheng workflow engine

## Request Specification
### Communication protocol
The RESTful interface of the workflow engine uses HTTP as the communication protocol, and the client sends requests to the server using Post. The request body is application/JSON, and the server responds to JSON data to the client. The encoding format uses UTF-8 unified format
```
{
  "code": 0,
  "success": true,
  "message": "",
  "data": [],
  "recordsTotal": "10"
}
```
**Result parameter description:**

| code         | Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                       |
|--------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| code         | int         | 0 indicates correct business execution.<br> 900 indicates incorrect request parameters.<br> 901 fails to obtain tenant information. <br>905 has incorrect username or password. <br>1000 lacks login credentials. <br>1001 is illegal.<br> 1002 has expired. <br>1003 has incorrect time parameters. <br>1004 has incorrect name or id. <br>1005 cannot set the agent as itself. <br>9999 system server exception |
| success      | boolean     | Is it correct to mark the completion of this request business? When it is true, the code is 0                                                                                                                                                                                                                                                                                                                     |
| message      | String      | Error return information description                                                                                                                                                                                                                                                                                                                                                                              |                  
| data         | Object/List | The data returned when the request is executed correctly or incorrectly. Please refer to the detailed interface description                                                                                                                                                                                                                                                                                       | 
| recordsTotal | String      | The total number when the data is of list type                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                                                                       |

Request address description:
http://127.0.0.1:8080/${apppath}/${prefix}/${api}${suffix} <br>
apppath: Project name <br>
prefix:Interception path: default value is horizon/workflow/rest <br>
api: Each specific business interface <br>
suffix:Request suffix for business interface: default value is: .wf <br>
If the project name is 'demo', the project deployment address is '127.0.0.1', the port is '8080', and the business interface is 'test', then the request address is: <br>
http://127.0.0.1:8080/demo/horizon/workflow/rest/test.wf <br>
Subsequent requests will be explained using this case study

## Obtain login authentication
### Login
In order to identify users, the workflow engine generates a secure accessToken for each logged in user through this interface. When accessing the workflow engine, users must request the server with the accessToken and other parameters. The accessToken expires in 5 days.<br>
Interface Request Invoking Description <br>
HTTP Request Method: POST <br>
Request Address: http://127.0.0.1:8080/demo/horizon/workflow/rest/user/login${suffix} <br>
**Post Data Description：**
```
{
  "loginName": "",
  "password": "",
  "tenantCode": ""
}
```
Request Parameter Description:

| Parameter  | Required | Description                 |
|------------|----------|-----------------------------|
| loginName  | Yes      | User Name                   |
| password   | Yes      | Password                    |
| tenantCode | No       | Empty in single tenant mode |
**Example of returned results：**
```
{
  "code": 0,
  "data": {
    "deptName": "Huizheng Software",
    "userName": "Admin",
    "accessToken": "TUfKbStH79iCdo3J%2f%2bQXz%2f9NrA3ikDYoprzftK8uxVxXDyDtzldY3fcYmS4r8uJm"
  },
  "message": "",
  "recordsTotal": "",
  "success": true
}
```
**Result parameter description:**

| Parameter   | Type   | Description                                    |
|-------------|--------|------------------------------------------------|
| accessToken | String | Invoking interface credentials, unique user ID |
| deptName    | String | Department Name                                |
| userName    | String | User Name                                      |

### Test Connection
Interface Request Invoking Description<br>
HTTP Request Method: POST <br>
Request Address: http://127.0.0.1:8080/demo/horizon/workflow/rest/testConnection${suffix} <br>
**Example of returned results：**
```
{
  "code":0,
  "message": "Connection test successful",
  "success": true
}
```
When the success value is 'True', it indicates that the access project path is correct.

### Interface Example
All interfaces need to carry the user credential accessToken, that is, the request parameter is：
```
{
  "accessToken": "${ accessToken }",
  "otherParams": ""
}
```
For example, the following user information query interface example：
HTTP Request Method: POST <br>
Request Address: http://127.0.0.1:8080/demo/horizon/workflow/rest/user/searchUser{suffix} <br>
**Post Data Description：**
```
{
  "accessToken": "",
  "searchUser": ""
}
```
Request Parameter Description:

| Parameter   | Required | Description                                               |
|-------------|----------|-----------------------------------------------------------|
| accessToken | Yes      | Invoking interface credentials, unique user ID            |
| searchUser  | Yes      | Fuzzy query of user name, if empty, return value is empty |
**Example of returned results:**
```
{
  "code": 0,
  "data": [
    {
      "id": "HZ28821856ef63420156ef6342a20002",
      "name": "User01",
      "login": "user01"
    }
  ],
  "message": "",
  "recordsTotal": "1",
  "success": true
}
```
**Result parameter description:**

| Parameter | Type   | Description |
|-----------|--------|-------------|
| id        | String | User ID     |
| name      | String | User Name   |
| login     | String | Login name  |
