响应结构
所有 API 响应遵循统一的 JSON 结构,包含三个顶层字段:data、status 和 error_code。这种标准化格式便于以编程方式处理响应。
成功响应
请求成功时,响应在 data 字段中包含所请求的数据:
成功响应 200 OK
data
包含实际响应载荷。结构因接口而异,列表接口通常包含 items 数组和分页元数据
status
表示请求是否成功的布尔值。成功请求为 true,错误时为 false
error_code
表示结果的数字码。0 表示成功,非零值表示特定错误(参见错误处理指南)
分页
列表接口返回带有元数据的分页结果,帮助您浏览大型数据集:
total— 所有页面的数据总条数page— 当前页码(从 1 开始)size— 每页数据条数items— 当前页的结果数组复杂数据结构
部分接口返回包含多语言字段和规范化标识符的嵌套对象:
复杂响应
多语言字段
像 display_name 这样的字段包含带有语言代码的翻译数组:
"display_name": [{ "lang": "EN", "name": "..." }] 规范化 ID
实体同时包含唯一 ID(drug_id、target_id)和规范化 ID,用于跨不同命名规范对相似实体进行分组
响应头
重要的元数据包含在响应头中:
content-type响应格式始终为 application/json
x-correlation-id请求追踪用于请求追踪和调试的唯一标识符
x-openapi-amountAPI 用量本次请求消耗的 API 调用量
date响应时间服务器生成响应时的时间戳
server服务器信息API 网关服务器信息(APISIX)
最佳实践
- 处理数据前始终检查 status 字段
- 对大型结果集正确处理分页
- 使用 x-correlation-id 进行调试和请求追踪
- 根据应用的语言环境解析多语言字段