跳转至

通用说明

XuperBaas API调用遵循HTTP协议

正式环境域名为 https://xuperbaas.baidu.com

所有request/response body内容均采用UTF-8编码。

API认证机制

所有API的安全认证一律采用非对称请求签名机制。对于每个HTTP请求，使用下面所描述算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。

认证字符串生成公式

auth-v{version}/{timestamp}/{sign}
  • version是正整数，目前支持1
  • timestamp是生成签名时的间戳，精确到毫秒，长度为13
  • 签名有效期是60秒
  • sign是针对url的QueryString的签名，先计算请求参数哈希，然后使用非对称私钥计算签名值，最后做hex编码。

sign生成公式

sign = hex(ecdsaSign(sha256(signString), privateKey))
  • privateKey为非对称私钥，与头域的X-User-Pubkey对应的私钥
  • signString包含两个部分，signString = timestampString + canonicalQueryString:
    • timestampString为时间戳字符串，与Authorization中时间戳一致，转换公式为 _={timestamp}
    • canonicalQueryString是对于URL中的Query String（Query String即URL中“？”后面的“key1 = value1 & key2 = value2 ”字符串）进行编码后的结果。

canonicalQueryString编码步骤

提取URL中的Query String项，即URL中“？”后面的“key1 = value1 & key2 = value2 ”字符串。 将Query String根据&分隔符拆开成若干项，每一项是key=value或者只有key的形式。 对拆开后的每一项进行编码处理，转换公式为 key + "=" + value 的形式。这里value不可以是空字符串。 将每一项转换后的字符串按照key字典顺序（ASCII码由小到大）排序，并直接拼接起来，生成相应的canonicalQueryString。 编码示例：

获取URL为http://127.0.0.1:8085/xbaas/v1/xchain/network/1/chain/xuper/totalTxHis?endTime=152324432942&type=1&num=3
的canonicalQueryString。

提取URL中的Query String，得到endTime=152324432942&type=1&num=3。
根据&对Query String进行拆分，得到endTime=152324432942、type=1、num=3三项。
对上面三项key进行（按照ASCII码由小到大）排序，得到结果是endTime=152324432942、num=3、type=1，然后直接拼接起来，得到CanonicalQueryString为endTime=152324432942num=3type=1。

如果时间戳是1648866157851，可以得到signString为_=1648866157851endTime=152324432942num=3type=1。

响应结构体说明

  • Content-Type: 默认类型为application/json，特殊情况下面接口会说明
  • 状态码都返回200，具体响应中code为0则为接口调用没有问题，code不为0则具体查看msg错误信息

无分页响应体定义:

字段 类型 说明
msg string 响应消息
code string 状态码，和HTTP状态码有区别，code为0则成功，不为0则具体查看msg错误信息
data object 具体数据

有分页响应体定义:

字段 类型 说明
msg string 响应消息
code string 状态码，和HTTP状态码有区别，code为0则成功，不为0则具体查看msg错误信息
data object 结构体定义如下

分页响应object定义:

字段 类型 说明
count int 数据总条数
data []object 具体数据

响应示例:

{
    "code": "0",
    "msg": "ok|err messages",
    "data": {}
}