View Categories

OpenAPI 鉴权与通用响应格式

请求鉴权

所有 OpenAPI 请求都必须包含以下 Header：

Header是否必填说明
user-id是QuarkIP 提供的客户端 ID
access-key是QuarkIP 提供的 API Key

请求示例：

GET /openapi/static/node/list?page_no=1&page_limit=20 HTTP/1.1
Host: {domain}
client-id: {your-user-id}
access-key: {your-access-key}

如果凭证缺失、无效或不匹配，接口可能返回 401 和 authentication error。

凭证安全建议

  • 仅在服务端保存和使用 API 凭证。
  • 不要在浏览器端 JavaScript、移动端安装包或公开代码仓库中硬编码 access-key。
  • 不要在工单、聊天记录或截图中发送完整 Token。
  • 建议将凭证保存在环境变量或专用的密钥管理服务中。
  • 如果怀疑凭证泄露，请停止使用该凭证并联系 QuarkIP 支持团队处理。

单条数据响应

返回单个对象的接口使用以下结构：

{
  "code": 0,
  "msg": "Ok",
  "info": {}
}

字段说明：

字段说明
code结果码；0 表示成功
msg结果说明；成功时通常为 Ok
info接口返回的数据对象

列表数据响应

返回列表的接口使用以下分页结构：

{
  "code": 0,
  "msg": "Ok",
  "info": {
    "items": [],
    "item_total": 0,
    "page_no": 1,
    "page_limit": 20
  }
}
字段说明
info.items当前页的数据列表
info.item_total符合条件的记录总数
info.page_no当前页码
info.page_limit当前页最多返回的记录数

判断请求是否成功

收到响应后，建议同时检查 HTTP 状态和响应体中的 code：

  1. 确认请求已正常收到 HTTP 响应。
  2. 确认响应体 code 为 0。
  3. 从 info 读取业务数据。
  4. 如果 code 不为 0，记录 code 和 msg，再根据错误码进行处理。

请勿只根据 msg 文本判断结果，因为错误提示文字可能随具体校验场景变化