跳到主要内容

基本规则

基本信息​

所有的API请求必须使用HTTPS。

数据格式​

所有的API请求必须使用HTTPS。

参数兼容性​

  • 请求是否成功，与请求参数的顺序无关
  • 请求是否成功，与请求JSON中的键值对出现的顺序无关
  • 请求和响应头的 key，忽略大小写，例 content-type 与 Content-Type等价。
  • 处理应答时，不应假设应答JSON中的键值对出现的顺序
  • 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
  • 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
  • 当请求或应答中的JSON键值对的值为空（null）时，可以省略

字符集​

仅支持UTF-8字符编码的一个子集：使用一至三个字节编码的字符。不支持Unicode辅助平面中的四至六字节编码的字符。

错误信息​

使用HTTP状态码来表示请求处理的结果。

  • 处理成功的请求，如果有应答的消息体将返回200。
  • 请求处理失败时，如缺少必要的入参，或者参数错误，将会返回4xx范围内的错误码。
  • 请求处理时发生了服务系统错误，将返回500/501/503的状态码。这种情况比较少见。

错误码和错误提示​

当请求处理失败时，除了HTTP状态码表示错误之外，API将在消息体返回错误相应说明具体的错误原因。

  • code：详细错误码
  • message：错误描述，使用易理解的文字表示错误的原因。
  • details: 错误细节，用于查看具体错误原因

User Agent​

  • 使用HTTP客户端默认的 User-Agent。
  • 遵循HTTP协议，使用自身系统和应用的名称和版本等信息，组成自己独有的User-Agent。