Supported Regions:上海

OpenAPI Interface Calling Methods

Under software deployment, the domain name and authentication mechanism acquisition methods for OpenAPI interface calls are different. This document provides detailed explanations.

1. Interface Usage Instructions

1.1 Domain Name (Access Address)

Note

The address for accessing WeDa after software deployment is generally http://ip:port, which is the access address for OpenAPI interfaces

Description

If using HTTPS, change the protocol to https; if you have a domain name, replace the IP with the specific domain name
Fill in the port with the actual port number used during deployment
- HTTP default port 80 can be omitted
- HTTPS default port 443 can be omitted

Environment ID Acquisition:

The environment ID can be obtained from the browser's address bar, which is the request parameter value starting with envId.

1.2 Authentication Mechanism

1.2.1 Obtain Secret Keys

Go to the Environment Configuration in the software management page to obtain SecretId and SecretKey.

环境配置

1.2.2 Obtain Access Token

Use OAuth 2.0 authentication method to exchange for Access Token.

Token Acquisition URL:

http://ip:port/auth/v1/token/clientCredential
# Replace http://ip:port with the specific access address

Request Example:

Method: POST
Headers:
- Content-Type: application/json
- Authorization: Basic <Base64(SecretId:SecretKey)>
Body:
```
{
  "grant_type": "client_credentials"
}
```

Return Value Format:

{
  "token_type": "Bearer",
  "access_token": "xxxxyyyy",
  "expires_in": 259200
}

Description

access_token: Access token, used for subsequent API calls
expires_in: Access Token validity period, unit: seconds

1.2.3 Use Access Token to Request Interface

Add the following in the Request Header:

Authorization: Bearer <access_token>

1.3 Request Instructions

All interfaces communicate via HTTP/HTTPS using UTF-8 encoding
Supported HTTP request methods: POST, GET, PUT, DELETE
Content-Type type: application/json;utf-8

2. Operation Examples

The following demonstration uses approval workflow OpenAPI interface calls as an example.

2.1 Node.js Code Example

Interface Acquisition Instructions

Interface information can be obtained from APIs Connector → Workflow.

For example: Query process instance approver list

{{vars.host}}/weda/workflow/v1/{{WeDa.EnvType}}/DescribeInstanceApproverList

Parameter Description:
1. {{vars.host}} - Domain name mentioned above
2. {{WeDa.EnvType}} - Environment value: prod (production environment) or dev (experience environment)

Code Example:

const Koa = require("koa");
const fetch = require("node-fetch");
const app = new Koa();

const SecretId = ""; // Obtain from software "Environment Configuration" page
const SecretKey = ""; // Obtain from software "Environment Configuration" page
const EnvType = "prod"; // prod: production environment, dev: experience environment

// Domain name
const domain = 'Replace with actual domain value';

app.use(async (ctx) => {
  // 1. Exchange for AccessToken
  const tokenResponse = await fetch(
    `${domain}/auth/v1/token/clientCredential`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${Buffer.from(
          `${SecretId}:${SecretKey}`
        ).toString("base64")}`,
      },
      body: JSON.stringify({
        grant_type: "client_credentials",
      }),
    }
  );

  const { access_token } = await tokenResponse.json();

  // 2. Request server-side API
  const queryResponse = await fetch(
    `${domain}/weda/workflow/v1/${EnvType}/DescribeInstanceApproverList`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${access_token}`,
      },
    }
  );

  ctx.body = await queryResponse.json();
});

app.listen(3000);

2.2 Call Interface Using Postman

2.2.1 Create Request

Open the Postman tool and add a request (specific request method can be viewed in APIs Connector → Workflow).

创建请求

Configure Global Environment Variables:

Description

You need to set the following global environment variables:

vars.host - Domain address
WeDa.EnvType - Environment value: prod (production environment) or dev (experience environment)
SECRET_ID - Obtain from Environment Configuration in the software management page
SECRET_KEY - Obtain from Environment Configuration in the software management page

环境变量配置

2.2.2 Configure Authorization

Go to the Authorization tab and set {{access_token}}.

Authorization 配置

2.2.3 Configure Pre-request Script

Go to the Script tab and set the following code in Pre-request:

Pre-request Script

Code Content:

// Check if there is a valid access_token
const accessToken = pm.environment.get("access_token");
const expiry = pm.environment.get("access_token_expiry");
const secretId = pm.globals.get("SECRET_ID");
const secretKey = pm.globals.get("SECRET_KEY");
const host = pm.globals.get("vars.host");
const now = Math.floor(Date.now() / 1000);

// If token exists and has not expired, skip acquisition
if (accessToken && expiry && now < expiry) {
    console.log("Token is valid, skipping acquisition");
    return;
}

console.log("Token does not exist or has expired, acquiring...");

// Define request parameters
const tokenUrl = host + "/auth/v1/token/clientCredential";
console.log("Token request address:", tokenUrl);

// Construct Basic Auth
const credentials = btoa(`${secretId}:${secretKey}`);

// Synchronously request to get token
pm.sendRequest({
    url: tokenUrl,
    method: 'POST',
    header: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${credentials}`
    },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            grant_type: "client_credentials"
        })
    }
}, function (err, res) {
    if (err) {
        console.error("Failed to get token:", err);
        return;
    }

    if (res.status !== 'OK') {
        console.error("Token interface returned error:", res.status, res.text());
        return;
    }

    const jsonResponse = res.json();
    const newToken = jsonResponse.access_token;
    const expiresIn = jsonResponse.expires_in || 3600; // Default 1 hour

    if (!newToken) {
        console.error("Returned access_token is empty");
        return;
    }

    // Save token and expiration time (expire 60 seconds early to prevent edge cases)
    const expiresAt = Math.floor(Date.now() / 1000) + expiresIn - 60;
    pm.environment.set("access_token", newToken);
    pm.environment.set("access_token_expiry", expiresAt);

    console.log("Token acquired successfully and saved");
});

2.2.4 Configure Headers

Go to the Headers tab and set the corresponding parameters.

Headers 配置

2.2.5 Configure Body

Go to the Body tab and set the corresponding request data.

Body 配置

2.2.6 Send Request

Click the Send button to send the request.

发送请求

3. Interface Exception Returns

There are two formats for interface exception returns:

3.1 Common Parameter Validation Exception

Return Format:

{
  "code": "INVALID_ACCESS_TOKEN",
  "requestId": "79e7c0fc8286e",
  "message": "access token verify failed: jwt expired"
}

Error Code Description:

Error Code	Description
`INVALID_ACCESS_TOKEN`	TOKEN is incorrect or expired
`BAD_REQUEST`	Request data format exception
`INVALID_HOST`	HOST is invalid
`INVALID_REGION`	Region mismatch
`INVALID_ENV`	Wrong environment, environment not found
`INVALID_ENV_STATUS`	Environment status exception, unavailable
`INVALID_COMMON_PARAM`	Common parameter error
`SIGN_PARAM_INVALID`	Signature verification failed
`PERMISSION_DENIED`	Permission denied
`EXCEED_REQUEST_LIMIT`	Resource limit exceeded
`EXCEED_RATELIMIT`	QPS limit exceeded
`SYS_ERR`	System error
`SERVER_TIMEOUT`	Service timeout

3.2 Business Interface Exception

Return Format:

{
  "Response": {
    "RequestId": "",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "Parameter error"
    }
  }
}

Error Code Description:

Please refer to the description in each interface document for specific error codes.

4. OpenAPI Modules Supported by Software Deployment

In addition to the approval workflow interface calls explained above, the following modules also support calling via OpenAPI under software deployment.

Description

For domain name acquisition methods, please refer to section 1.1 Domain Name (Access Address) of this document
For Token acquisition methods involved in the authentication mechanism, please refer to section 1.2 Authentication Mechanism

OpenAPI Interface Calling Methods

1. Interface Usage Instructions​

1.1 Domain Name (Access Address)​

1.2 Authentication Mechanism​

1.2.1 Obtain Secret Keys​

1.2.2 Obtain Access Token​

1.2.3 Use Access Token to Request Interface​

1.3 Request Instructions​

2. Operation Examples​

2.1 Node.js Code Example​

2.2 Call Interface Using Postman​

2.2.1 Create Request​

2.2.2 Configure Authorization​

2.2.3 Configure Pre-request Script​

2.2.4 Configure Headers​

2.2.5 Configure Body​

2.2.6 Send Request​

3. Interface Exception Returns​

3.1 Common Parameter Validation Exception​

3.2 Business Interface Exception​

4. OpenAPI Modules Supported by Software Deployment​

4.1 MySQL Database​

4.2 Data Model​

4.3 Cloud Storage​

1. Interface Usage Instructions

1.1 Domain Name (Access Address)

1.2 Authentication Mechanism

1.2.1 Obtain Secret Keys

1.2.2 Obtain Access Token

1.2.3 Use Access Token to Request Interface

1.3 Request Instructions

2. Operation Examples

2.1 Node.js Code Example

2.2 Call Interface Using Postman

2.2.1 Create Request

2.2.2 Configure Authorization

2.2.3 Configure Pre-request Script

2.2.4 Configure Headers

2.2.5 Configure Body

2.2.6 Send Request

3. Interface Exception Returns

3.1 Common Parameter Validation Exception

3.2 Business Interface Exception

4. OpenAPI Modules Supported by Software Deployment

4.1 MySQL Database

4.2 Data Model

4.3 Cloud Storage