RIVALSA文档中心

调用方式

发布时间:2022-05-01 17:00:00

一、请求结构

通信协议

为保证您与我们之间的通信安全,调用我们的 API 时统一采用 HTTPS 协议。

通信地址

我们的 API 的通信域名统一为 api.rivalsa.net

每个接口的具体地址会在各 API 单独的文档中注明。

请求方法

我们的 API 仅支持 POST 方法,且 POST 请求的 Content-Type 必须为 application/json;charset=UTF-8

请注意:Content-Type 必须与以上描述完全一致,建议直接复制以上值,包括但不限于下表中的 Content-Type 将会引发错误:

错误的 Content-Type 错误原因
application/json 值不完整,缺少“;charset=UTF-8”
application/json; charset=UTF-8 “charset”前面多一个空格
application/json;charset=utf-8 “utf”三个字符写成了小写
application/json;charset=UTF8 “UTF”与“8”之间缺少减号(-)
字符编码

我们的 API 均使用 UTF-8 编码。

二、公共请求头部(HTTP Header)

调用我们的任何 API 均需携带公共请求头部,我们在每个 API 单独的文档中不再重复介绍公共请求头部了,所有的公共请求头部都是必选的。公共请求头部如下表所示:

字段 描述
X-CLIENTTIMESTAMP 您发起请求时的 UNIX 时间戳。
X-CLIENTRAND 随机字符串。
X-APID 我们发放给您的 APID,如果您没有 APID 请联系我们获取。
Authorization 本次请求对应的签名,计算方法请参考下文的签名算法

三、签名算法

安全凭证(APIkey)

当我们给您发 APID 时,会同时给您发放 APIkey,用于验证您的身份。您必须严格保管 APIkey,不得泄露给任何第三方,如已泄露,请立刻联系我们禁用此 APIkey。

签名计算过程
1.计算 HashedRequestBody

计算请求 body 的 sha512 值,其伪代码为 Lowercase(HexEncode(Hash.sha512(body)))

2.拼接字符串 StringToSign

将 action、X-CLIENTTIMESTAMP、X-CLIENTRAND 及 HashedRequestBody 的值拼接到一起。

每个 API 的 action 的值不同,会在每个 API 单独的文档中注明。

3.计算 HashedStringToSign

计算请求 StringToSign 的 sha512 值,其伪代码为 Lowercase(HexEncode(Hash.sha512(StringToSign)))

4.计算 Authorization

以 APIKey 为密钥参数(key),HashedStringToSign 为消息参数(data),计算 hmac_sha512 值,其伪代码为 Lowercase(HexEncode(Hash.hmac.sha512(HashedStringToSign, APIKey)))

签名示例

例如,请求的相关参数如下表所示:

参数
APIkey Gu5t9xGARNpq86cd98joQYCN3AKIDz8krbsJ5yKBZQpn74WFkmLPx3
请求 body {"name":"Rivalsa","sex":"M","age":18}
action testAction
X-CLIENTTIMESTAMP 1650293419
X-CLIENTRAND 14580021

按照签名计算过程计算签名的中间值及最后的签名如下表所示:

参数 计算过程(伪代码)
HashedRequestBody 6bf99ad72f53a8f94b2d303462df8cebbddf3296df920e2e736ec6181dfd5c9c685babefba9f8011ed900c0ab30de886f82bd70e500110a7484806d683834716 Lowercase(HexEncode(Hash.sha512("{\"name\":\"Rivalsa\",\"sex\":\"M\",\"age\":18}")))
StringToSign testAction1650293419145800216bf99ad72f53a8f94b2d303462df8cebbddf3296df920e2e736ec6181dfd5c9c685babefba9f8011ed900c0ab30de886f82bd70e500110a7484806d683834716 testAction + 1650293419 + 14580021 + 6bf99ad72f53a8f94b2d303462df8cebbddf3296df920e2e736ec6181dfd5c9c685babefba9f8011ed900c0ab30de886f82bd70e500110a7484806d683834716 (加号表示字符串的拼接)
HashedStringToSign 2965ace7dc13fc9db5e8bc802347c56c1fb45de9068ba47209bdb5f327f9406bec4882ca7b06c24327a292bcd3d5a2fbe5c30d2d9d6bcf1b6ec4e96f7fe0a9c8 Lowercase(HexEncode(Hash.sha512("testAction1650293419145800216bf99ad72f53a8f94b2d303462df8cebbddf3296df920e2e736ec6181dfd5c9c685babefba9f8011ed900c0ab30de886f82bd70e500110a7484806d683834716")))
Authorization c931dd6b1efbfa1b8e2e6166b9d8accd3e6f54ba51496f4965e7416667cc396cd96e05faef613f9383086cd27969d6158f772fcc156fd797c1cdc62fb496d5a4 Lowercase(HexEncode(Hash.hmac.sha512("2965ace7dc13fc9db5e8bc802347c56c1fb45de9068ba47209bdb5f327f9406bec4882ca7b06c24327a292bcd3d5a2fbe5c30d2d9d6bcf1b6ec4e96f7fe0a9c8", "Gu5t9xGARNpq86cd98joQYCN3AKIDz8krbsJ5yKBZQpn74WFkmLPx3"))) (消息参数(data)在前,密钥参数(key)在后)

四、响应

HTTP 状态码

只要您的请求被我们处理,无论成功与否,响应的 HTTP 状态码均为 200。

Content-Type

响应的 Content-Type 均为 application/json;charset=UTF-8。

公共响应头部(HTTP Header)

您调用我们任何一个 API 后(无论成功还是失败),都会在 HTTP Header 中返回以下字段。

字段 描述
code 错误码,若错误码为0,则表示请求成功,否则表示请求失败。若请求失败,可根据错误码到当前文档的公共错误码部分或相应 API 单独的文档中查询错误原因。
公共响应体(HTTP body)
成功响应

若您调用成功会给您返回成功响应。由于个别 API 涉及较复杂的多层结构,成功响应仅表示本层处理成功,判断全局成功的条件会在相应 API 单独的文档中介绍。成功响应 body 是由以下字段组成的 json 字符串:

字段 类型 描述
code Integer 错误码,成功响应的错误码固定为0。
response 不同 API 类型不同 具体的响应内容,您调用不同 API 此处的内容会有所不同,具体请参考相应 API 单独的文档。若您调用的 API 的响应体为空,则此处可能没有此字段。
requestID Integer 本请求的 ID,需联系我们定位问题时,请提供此值。
失败响应

若您调用失败会给您返回失败响应。失败响应 body 是由以下字段组成的 json 字符串:

字段 类型 描述
code Integer 错误码,失败响应的错误码为除了0以外的其他数字。可根据错误码到当前文档的公共错误码部分或相应 API 单独的文档中查询错误原因。
msg String 简单的错误描述。
requestID Integer 本请求的 ID,需联系我们定位问题时,请提供此值。

五、公共错误码

错误码 描述
1 参数 X-CLIENTTIMESTAMP 提供的时间戳距离当前时间超过5分钟。
2 参数 X-CLIENTRAND 的值在当前时间前5分钟内出现过。
3 您使用的 apid 不存在。
4 您使用的 apid 不允许调用此 API。
5 您的签名与服务器端计算的签名不符。
6 系统错误,请联系我们处理。
7 您的签名不符合规则,签名只能是128位十六进制数字,字母部分必须小写。
8 参数 X-CLIENTTIMESTAMP 不符合规则,只能由10位数字组成,从左向右数第1位只能是数字1,从左向右数第2位必须不小于6。
9 您使用的 apid 不符合规则,apid 只能由大小写字母和数字组成。
10 系统错误,请联系我们处理。
11 系统错误,请联系我们处理。
12 系统错误,请联系我们处理。
13 系统错误,请联系我们处理。
14 系统错误,请联系我们处理。
15 系统错误,请联系我们处理。
16 您使用的 apid 已被暂停使用。
17 您使用的 apid 已欠费,请续费后再继续使用。

六、示例

请求示例
POST https://api.rivalsa.net/v2/example

Authorization:c931dd6b1efbfa1b8e2e6166b9d8accd3e6f54ba51496f4965e7416667cc396cd96e05faef613f9383086cd27969d6158f772fcc156fd797c1cdc62fb496d5a4
Content-Type:application/json;charset=UTF-8
Host:api.rivalsa.net
X-APID:dZmW39sZmbSgcD8wzSOZDa8uVhltPU3mPBcouuYR
X-CLIENTRAND:14580021
X-CLIENTTIMESTAMP:1650293419

{"name":"Rivalsa","sex":"M","age":18}
响应体示例
成功响应示例
{
    "code":0,
    "response":"example response",
    "requestID":1
}
失败响应示例
{
    "code":3,
    "msg":"apid不存在",
    "requestID":2
}