接口规范

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：

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 行按顺序组成，行间使用单个换行符，末尾不追加换行：

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：

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

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

请求参数

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

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

成功响应

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

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

列表使用 items 和 page：

{
  "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 仅在需要补充结构化上下文时出现：

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

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

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