---
title: "接口规范"
description: "App 身份调用业务接口时使用的认证、请求、响应和错误约定。"
image: "http://127.0.0.1:4321/docs/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: http://127.0.0.1:4321/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口规范

API 手册只收录面向 App 身份开放的开发对接接口。App 不需要登录或预先换取临时凭据；每次请求都必须独立携带 App 认证信息。除“获取系统状态”外，接口还要求为 App 授予目标资源和操作对应的访问策略（Policy）。

当前公开范围包括系统状态、数据库动态凭据创建与生命周期、主机受管账号当前凭据、密钥管理服务（KMS）在线操作，以及机密信息存储（Secret KV）。管理用户、系统配置、资源建模和运维控制接口不属于 App API。

## 基础约定

- 基础路径：`/api/v1`
- 请求和响应编码：UTF-8
- JSON 请求：`Content-Type: application/json`
- 时间：RFC 3339，例如 `2026-08-02T08:00:00Z`
- 二进制输入输出：无填充 Base64URL
- 客户端可发送 `X-Request-ID` 作为请求标识；未发送时由系统生成。响应 envelope 和 `X-Request-ID` 响应头使用同一值。

生产环境应通过 HTTPS 调用 API，避免 App Secret、签名材料和敏感业务数据在传输链路中暴露。

## Header 签名认证

推荐使用 SM2 签名凭据。每次请求携带以下 Header：

```http
X-QK-AppID: app_orders
X-QK-Timestamp: 2026-08-02T08:00:00Z
X-QK-Nonce: 019fb1ca-82f3-7c82-8cc5-0123456789ab
X-QK-Signature: <base64url-sm2-signature>
```

签名原文由以下 7 行按顺序组成，行间使用单个换行符，末尾不追加换行：

```text
METHOD
CANONICAL_PATH
CANONICAL_QUERY_WITHOUT_SIGNATURE
BODY_SM3
TIMESTAMP
NONCE
APPID
```

- `METHOD`：大写 HTTP 方法。
- `CANONICAL_PATH`：先进行 URL decode，再按 RFC 3986 percent-encode 得到的路径。
- `CANONICAL_QUERY_WITHOUT_SIGNATURE`：排除 `signature` 参数后，对 key 和 value 按字典序排序并按 RFC 3986 编码；没有 Query 时为空行。
- `BODY_SM3`：原始请求体字节的 SM3 摘要，使用小写十六进制；没有请求体时计算空字节串摘要。
- `TIMESTAMP`：与 `X-QK-Timestamp` 完全一致，可使用 RFC 3339 或 Unix 秒。
- `NONCE`：与 `X-QK-Nonce` 完全一致，并且在有效时间窗内不得重复。
- `APPID`：与 `X-QK-AppID` 完全一致。

使用 App 凭据对应的 SM2 私钥对上述 UTF-8 字节签名，再将签名结果编码为无填充 Base64URL，写入 `X-QK-Signature`。时间戳超出允许窗口、签名不匹配或 nonce 重复时，请求会被拒绝。

## App Secret 认证

受控内网集成也可以直接在 Header 中提交一次性创建或轮换时取得的 App Secret：

```http
X-QK-AppID: app_orders
X-QK-App-Secret: <app-secret>
```

App Secret 不得放入 URL、日志或错误信息。Header 签名和 App Secret 不能在同一请求中混用。

## 请求参数

每个接口页面按位置列出参数：

| 位置 | 含义 |
| --- | --- |
| Path | 接口地址中的 `{parameter}`；`{resource_path...}` 可以包含多级 `/` 路径 |
| Query | URL 查询参数；可选参数未提交时按接口默认值处理 |
| Body | JSON 请求体字段；未声明的字段会被拒绝 |

Secret KV 的写入接口是例外：请求体本身就是业务定义的 JSON 对象，不需要额外包裹 `data` 字段。具体请求以各接口页面的 cURL 示例为准。

## 成功响应

所有成功响应都使用统一 envelope。`request_id` 用于日志关联和问题排查，`error` 固定为 `null`。单个资源使用 `item`：

```json
{
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910",
  "data": {
"item": {}
  },
  "error": null
}
```

列表使用 `items` 和 `page`：

```json
{
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910",
  "data": {
"items": [],
"page": {
  "limit": 20,
  "next_cursor": "",
  "has_more": false
}
  },
  "error": null
}
```

无持久资源语义的在线操作使用 `result`。每个接口页面会展示其完整字段，而不是空对象。

## 失败响应

失败响应的 `data` 固定为 `null`，`error.code` 是可供程序判断的稳定代码，`message` 是面向人的说明，`details` 仅在需要补充结构化上下文时出现：

```json
{
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910",
  "data": null,
  "error": {
"code": "invalid_request",
"message": "请求参数或 JSON 请求体无效",
"details": {}
  }
}
```

通用错误代码如下。接口页面还会列出该业务操作可能返回的领域错误和完整响应示例。

| HTTP | `error.code` | 含义 |
| --- | --- | --- |
| 400 | `invalid_request` | Path、Query 或 JSON 请求体无效 |
| 400 | `not_initialized` | 系统尚未完成初始化 |
| 401 | `unauthorized` | App ID、Secret、签名或凭据状态无效 |
| 401 | `replayed_request` | 签名请求的 nonce 已经使用 |
| 403 | `forbidden` | App 没有目标资源所需权限 |
| 413 | `request_body_too_large` | 请求体超过服务端限制 |
| 423 | `sealed` | 系统处于封印状态 |
| 503 | `leader_unavailable` | 高可用集群 Leader 暂不可用 |
| 503 | `maintenance_mode` | 系统处于维护模式 |
| 500 | `internal_error` | 服务端无法完成请求 |

收到错误后应先记录 `request_id`。只有网络故障、`leader_unavailable` 或明确可重试的服务不可用错误适合退避重试；参数、认证、权限和业务状态错误应先修正原因。签名重试必须生成新的 nonce 和时间戳，并对本次实际请求重新签名。

Source: http://127.0.0.1:4321/docs/api/reference/index.mdx