3. APIP20V1_Avatar(zh-CN)

APIP20V1_Avatar(zh-CN)

  • 昌
     

    APIP20V1_Avatar(zh-CN)
Version:1
Language:zh-CN
Author:C_armX
Status:draft
Createddate:2022-03-07
Createddate:2022-03-07
Filehash:""
TXid:

    APIP20V1_Avatar(zh-CN)

    目录

    关于APIP

    本协议的基本共识

    接口名称

    接口说明

    请求参数

    响应参数

    返回值

    Type:APIP
SerialNumber:11
ProtocolName:HATOnChain
Version:1
Description:定义头像获取通用接口。
Author:C_armX
Language:zh-CN
preVersionHash:""

    关于APIP

    1. APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型，用于创建开放的API文档，并且按照《FEIP1_FreeProtocol》协议发布在Freecash主链上。

    2. API的URL路径由服务方按照《FEIP29_Service》协议发布在Freecash主链上。

    3. APIP类型协议的一般共识在《APIP1_OpenAPI》中描述，包括接口标识、连接方式、请求方式、数据验证、常用参数、筛选与排序方式等。

    4. 按照《APIP1_OpenAPI》，API请求方向API服务方请求连接和请求数据的流程概括如下:

      • 建立连接：请求方通过connect接口提交私钥签名，请求连接API服务，成功后获得对称密钥symKey用于数据请求和验证。

      • 准备参数：准备请求参数，注意，采用POST方法时，需包括该API的url。

      • 参数排序：所有请求参数按字母升序排列，不区分大小写。

      • 数据签名：将symKey追加至参数末尾，然后经两次sha256哈希获得签名sign。

      • 发送请求：删除symKey字段，将requester和sign追加至末尾，发送给服务方。

      • 验证请求：API服务方验证requester授权、sign、timestamp、POST方法url等均有效或正确后予以响应。

      • 响应数据：响应数据尾部加入symKey后做两次sha256哈希获得sign，再用sign替换symKey后将数据返回请求方。

      • 验证数据：请求方获得数据后，用symKey替换sign后哈希签名，值与sign值一致则接受数据。

    本协议的基本共识

    1. 本协议定义提供头像服务的接口通用格式。

    2. 头像的具体形成和分配方式由服务方自行设计。

    3. 示例数据：

    requester的地址:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

requester的公钥:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

requester的私钥:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

requester的symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

apiUrl:https://www.sign.cash/api/

    接口名称

    avatar

    接口说明

    批量获取fch地址对应的头像。

    请求参数

    name type description
    addressList string array The List of FCH addresses
    timestamp timestamp 请求的时间戳，精确到毫秒
    url string 请求的url，仅在post方法时出现
    sign string 用symKey对请求经两次sha256计算得到的签名，参见“构造请求示例”

    响应参数

    方案一：二进制文件，按大端序fch地址+图像大小+图像文件存放所有头像，在文件末尾加入symKey两次sha256哈希得到签名sign值，去除symKey，加入sign值，响应给请求者。
    方案二: 每个头像独立文件，文件名为fch地址。每个文件分别用symKey签名。

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Other error. 其他错误 signedRequest, errorMessage

    构造请求示例

    请求内容：获取FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的头像。

    参数

    {
	"addressList": ["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],
	"timestamp": 1635513688254
}

    GET：

    - unsignedRequest:

https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254

- sign = sha256(sha256(https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254&symKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=33333333333335555555555522222222211111111111111111111111111111

- signedRequest：

https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=33333333333335555555555522222222211111111111111111111111111111

    POST：

    - URL：https://www.sign.cash/api/cidInfo

- unsignedRequest:

{"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo"}

- sign = sha256(sha256({"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=555555555555555555555555522222222211111111111111111111111111111

- signedRequest：

{"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"555555555555555555555555522222222211111111111111111111111111111"}
    0
Log in to reply