RIVALSA文档中心

调用方式

一、请求结构

通信协议

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

通信地址

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

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

请求方法

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

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

字符编码

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

二、公共请求头部（HTTP Header）

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

三、签名算法

安全凭证（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)))

签名示例

例如，请求的相关参数如下表所示：

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

四、响应

HTTP 状态码

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

Content-Type

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

公共响应头部（HTTP Header）

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

公共响应体（HTTP body）

成功响应

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

失败响应

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

五、公共错误码

六、示例

请求示例

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
}