REST API/响应格式

响应格式

了解 API 响应结构、状态码和数据格式

响应结构

所有 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 进行调试和请求追踪
  • 根据应用的语言环境解析多语言字段