API definition
Every development mode defines an API through three parts: basic information, request parameters and response parameters. The development mode determines how the API executes; these three parts determine what the API looks like, how it is called and what structure it returns.
Basic information
Click "Basic information" on the right side of the workbench to open the configuration drawer.
| Field | Description | Constraint |
|---|---|---|
| API ID | Generated by the platform after saving | Read-only |
| API name | Display name, up to 100 characters | Required |
| API path | The platform's external path, prefixed with the project's unified prefix | Required; letters, digits, /, - and _ only; must not contain // |
| Request method | GET / POST / PUT / PATCH / DELETE | GET only for table mode, Elasticsearch and Hive |
| Operation type | Query / Insert / Update / Delete | Query only for table mode; Hive does not support insert |
| Visibility level | Public (visible to everyone) / Private (visible only to yourself) | Private APIs do not appear in other users' selectable lists |
| Authentication method | None / Simple (AppKey) / Signature (AppKey + AppSecret) | See the notes below |
| Release protocol | REST is always checked; MCP is optional | MCP is selectable only with simple authentication |
| API group | The group tree on the left determines where the API is filed | Required |
| API category | Business category used for list filtering | Optional |
| Enable transaction | Commits or rolls back as a whole when a write operation has multiple statements | Not shown in proxy and orchestration modes |
| Version | Positive integer | Required |
| Timeout | API execution timeout in ms | In proxy mode, set separately in the route configuration |
| Description | API purpose and caveats | Optional |
Authentication methods
| Type | Caller needs | Use case |
|---|---|---|
| None | No credential | Intranet or public data only; not recommended for production |
| Simple authentication | X-AppKey | Internal systems and MCP calls |
| Signature authentication | X-AppKey + signature headers | Open platforms and public internet calls; tamper-proof and replay-proof |
For the signature algorithm, request headers and verification flow, see Signature authentication. An API's authentication method only specifies the allowed authentication types; to actually call the API, an application credential must also be authorized for it.
Release protocols
- REST: Always enabled; this is the default way to call the API.
- MCP: When checked, the API is exposed to agents as an MCP tool. It can be checked only when the authentication method is "Simple authentication".
Request parameters
The "Request parameters" panel on the right defines what callers can pass.
| Field | Description |
|---|---|
| Parameter name | The externally exposed parameter name, referenced in SQL as #{parameterName} |
| Target parameter name | Proxy mode only: the parameter name mapped to the third party; if left empty, the same name is used |
| Parameter type | String / Int / Float / Array / Object / Boolean |
| Parameter location | Query / Body / Header; path parameters are detected automatically from #{name} |
| Required | Yes / No |
| Example value | Default example for documentation and the test panel |
| Default value | Used when the caller does not pass a value |
| Description | Parameter meaning |
| Child parameters | Click + to add nested structures for Object / Array |
Script mode supports Parse: it extracts #{} placeholders from the SQL automatically to generate parameters, reducing manual entry. If you rename a parameter, references in the SQL are not renamed automatically and must be updated accordingly.
Pagination parameters
Query-type SQL APIs can enable pagination:
- When enabled, two parameters,
pageNumandpageSize, are added automatically. pageSizehas an upper limit of 1000; non-positive or missing values fall back to the default.- Proxy, orchestration and Hive data sources do not offer this switch.
- In table mode, after you check pagination, the page generates the corresponding parameters.
Response parameters
The "Response parameters" panel on the right defines response fields and structure.
| Field | Description |
|---|---|
| Parameter name | The external response field name |
| Source field | SQL column name / script field / third-party field (depending on the mode) |
| Parameter type | String / Int / Float / Array / Object / Boolean |
| Location | In proxy mode, indicates whether the field sits in code, data, msg, timestamp, traceId or another location |
| Example value | Documentation example |
| Default value | Fallback value when the field is empty |
| Description | Field meaning |
| Child parameters | Nested object/array structure |
- Script mode can parse response parameters automatically from the SQL result.
- Proxy mode can import a response structure by pasting a third-party JSON response.
- Undeclared fields do not appear in the response examples of the API documentation, but whether the actual response is trimmed depends on the data plugin configuration.
Unified response structure
APIs return the platform's unified structure by default:
{
"code": 0,
"msg": "success",
"data": {},
"traceId": "..."
}
code=0means success; any non-zero value means a business failure.- For the mapping between error codes and HTTP status codes, see Error codes.
- Proxy mode keeps the third party's original response by default; it is converted into a platform business error only after error mapping is configured.
- Streaming or raw response support depends on the API type and the release protocol.
Save, release and versions
| Action | Result |
|---|---|
| Save | Writes a draft that does not serve traffic; an online API must be taken offline before saving |
| Release | Generates a release snapshot that takes effect in the current environment and sets the API status to online |
| Version upgrade | Copies the current definition with the version number + 1 and saves it as a new version |
| Take offline | Stops serving traffic while keeping the definition and history |
The version number is the business version of the API definition and is not the same as a release batch. For comparing, rolling back and migrating releases, see Environments and releases and Versions and migration.
Validation and common errors
| Message | Cause | Resolution |
|---|---|---|
| Please enter an API name | The name is empty | Enter a name |
| Invalid API path format | Contains Chinese characters, spaces or illegal characters | Keep only letters, digits, /, - and _ |
| Consecutive slashes are not allowed | The path contains // | Fix the path |
| Please select a group | No API group is selected | Select or create one in the group tree on the left |
| Take the API offline before saving | The API is online | Take it offline first, then save |
| Save before releasing | There are unsaved changes | Save first |
| MCP cannot be checked | The authentication method is not simple authentication | Switch to simple authentication |