请求和响应

基础 URL

所有的接口均有统一的基础 URL，具体与接入的服务环境有关。

生产环境的 URL 是 https://openapi.iflydocs.com，其他环境请参考 服务环境。

注意

生产环境和研发环境严格隔离，APPID 和用户数据均不互通。

请求参数

根据 HTTP 请求方法，有以下集中传参方式：

• GET 请求：通过 URL query 传参。
• POST 请求：通过 body 传参，Content-Type 为 application/json。
• PUT 请求：通过 body 传参，Content-Type 为 application/json。
• DELETE 请求[1][2]：通过 body 传参，Content-Type 为 application/json。

注[1]

这种方式不合理，后续将改为 URL query 传参。

注[2]

部分使用 token 的接口，使用 URL path 传参。请参考对应接口的说明。

请求鉴权

除特殊说明外，所有的接口都需要携带鉴权信息。

鉴权信息通过 HTTP 请求 Header 的 Authorization 字段携带。根据接口类型，分为两种：

令牌方式弃用

Authorization 的值为通过授权接口获取的 AccessToken。

签名方式

先通过请求参数和 AppSecret 进行 HMAC-SHA1 计算出签名 SIGN。详见 生成签名。

然后将 APPID 和签名通过 : 拼接得到 Authorization。

const Authorization = `${APPID}:${SIGN}`

响应参数

响应数据恒定为 JSON 格式，类型如下：

/** 通用响应 Body 结构（内部） */
interface IResponseBody<T, U = number> {
  /** 状态码，成功是为 0 */
  code: U
  /** 状态码描述 */
  message: string
  /** 响应数据 */
  data: U extends 0 ? T : null
}

示例：

{
  "code": 0,
  "message": "正常",
  "data": {
    "key": "value",
  }
}

具体说明如下：

参数	类型	备注
code	number	请求状态标识，0 代表成功。
message	string	提示信息。
data	Object | Array | null	返回数据内容。

具体的错误码说明，请参考 错误码大全。