APIP5V1_ProtocolInfo(zh-CN)



  • APIP5:Protocol
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Createddate:2021-11-20
    Update:2021-04-27
    PID:""
    TXID:
    

    APIP5V1_Protocol(zh-CN)

    目录

    关于APIP

    关于本协议

    getProtocolList

    getProtocolOpHistory

    getProtocolRateHistory


    Type:APIP
    SerialNumber:5
    ProtocolName:Protocol
    Version:1
    Description:定义协议信息查询接口。
    Author:C_armX
    Language:zh-CN
    PreVersionHash:""
    

    关于APIP

    概述

    APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型,用于创建和发布开放的API文档,供API服务方开发部署通用API服务,以实现数据服务的去中心化。API需求方可以按照APIP协议从遵循该协议的任何一个API服务方那里获取数据服务。

    通用规则

    《APIP1_OpenAPI》规范了APIP类型协议的协议发布接口标识接口URL构成时间戳格式密码算法服务流程商业模式连接接口数据接口查询语法的通用规则。设计、开发或应用APIP协议前,应先参考《APIP1_OpenAPI》协议。

    建立连接

    使用APIP协议各接口,须先采用《APIP1_OpenAPI》的connect接口从API服务方获取symKey。参见《APIP1_OpenAPI》的“connect接口”。

    通用请求参数

    APIP类型协议接口的通用请求参数如下:

    name type description requested
    requester string 请求方的fch地址 Y
    url string 当前所请求api的url Y
    timestamp timestamp 发起请求的时间戳,精确到毫秒 Y
    query object 请求数据的查询语句,参见”APIP简易查询语法@APIP1“ N
    sort object 请求数据的排序语句,参见”APIP简易查询语法@APIP1“ N
    from int 请求列表数据时的起始位置,从0开始 N
    size int 请求列表数据时的每页条目数 N
    sign string 用symkey对其他参数所做的签名 Y

    通用响应方式

    响应前所作的验证、通用响应状态码、通用响应参数参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。

    请求成功的通用响应参数为:

    参数 类型 说明 适用状态
    code int 响应状态码 all
    message string 响应状态描述 all
    data object 正常返回数据,由具体APIP定义。 0
    sign string 将symKey加入响应参数做两次sha256哈希的签名值 all

    具体APIP协议的特定响应参数在data参数中给出,并定义具体接口的响应状态。

    请求失败的通用响应码、响应信息和响应参数,参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。

    签名与验证

    APIP接口的请求和响应都需要签名和验证。

    connect接口请求时用私钥签名,公钥验证,响应时无需签名。

    所有数据请求和数据响应,采用以下方法:

    签名:将对称密钥symKey加入参数压缩升序后计算两次sha256,得到sign的值,再用sign替换参数中的symKey。

    验证:将sign从参数中取出,加入symKey,压缩升序后做两次sha256计算,将值与sign的值比较,一致则验证通过。

    详见《APIP1_OpenAPI》

    关于本协议

    1. 本协议接口提供链上注册的各种协议的相关信息。

    2. 本协议接口的数据来源遵循以下协议:

      • 《FEIP1_FreeProtocol》
    3. 本协议接口数据采用JSON格式。

    4. 示例数据:

    requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

    服务方链上发布的urlMainPart: https://www.sign.cash/api/

    接口url:https://www.sign.cash/api/apip5/v1/[接口名称]


    getProtocolList

    获取协议信息列表。

    url

    [服务方发布的urlMainPart]apip5/v1/getProtocolList

    示例:

    https://www.sign.cash/api/apip5/v1/getProtocolList

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询pid为“222220000000000011111”和“33333000000002222222222”的协议最新详情。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip5/v1/getProtocolList",
    	"query": {
    		"terms": {
    			"pid": ["222220000000000011111","33333000000002222222222"]
    		}
    	},
    	"sign": ""
    }
    

    响应参数

    通用参数参见通用响应方式。本接口响应参数:

    • data
    name type description requested
    list object See below
    total uint The total number of items. Y
    bestHeight uint The latest block height when getting the data. Y
    • data.list
    name type description key in FEIP1
    pid string The ID of the protocol,that is,the double sha256 value of the protocol file. data.pid
    type string The type of the protocol, such as"FEIP". data.type
    sn string The serial number in this type of protocol. data.sn
    ver string The version of the protocol. data.ver
    name string The name of the protocol. data.name
    lang string The language of the protocol being registered, formatted with i18n(internationalization), such as "en-US". data.lang
    title string Makeup by:type+sn+"V"+ver+'_'+name+'('+language+')',such as:FEIP3V4_CID(en-US)
    desc string Thedescriptionoftheprotocol. data.desc
    authors string The authors of the protocol. data.authors
    prePid string Double sha256 value of the previous version protocol file. data.prePid
    fileUrl string array Locations to find the protocol file. data.fileUrl
    signer string The signer of the first input of the transaction in which the protocol was first published.
    firstTxid string The txid of the transaction in which the protocol was first published.
    firstTimestamp timeStamp The timeStamp of the transaction in which the protocol was first published.
    firstBlockHeight uint The height of the block in which the protocol was first published.
    lastTxid string The txid of the last operation of the protocol.
    lastTimestamp timeStamp The transaction timestamp of the last operation of the protocol.
    firstBlockHeight uint The height of the block of the last operation of the protocol.
    tCdd uint64 The total destroyed coindays of all transactions where the value of data.op is "rate".
    tRate float Cumulative rating score. tRate=(tCdd*tRate+cdd*rate)/(tCdd+cdd)
    status bool Is the protocol in effect.
    • 示例

    响应pid为“222220000000000011111”和“33333000000002222222222”的协议最新详情。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    				"pid": "222220000000000011111",
    				"type": "FEIP",
    				"sn": "3",
    				"ver": "4",
    				"name": "CID",
    				"lang": "zh-CN",
    				"title": "FEIP3V4_CID(zh-CN)",
    				"desc": "Register or unregister a human friendly identity for an address.",
    				"authors": ["FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv", "FS2AWq1dgdhCpNTwqfBbMBBJGNNj1LSboy", "FLx88wdsbLQyZRmbqtpeXA9u5FG9EyCash"],
    				"prePid": "bd0429aaf6d7784958a36473f2f925d8d2ca76125cc610adf2afb1956a1d56b2",
    				"fileUrl": ["https://github.com/freecashorg/FEIP/FEIP3_CID/"],
    				"firstTxid": "dde54b27326c11236676dfd5b3c030539a72e39924e7ad835b70ff16a5647715",
    				"signer": "FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv",
    				"firstTimestamp": 1610261291,
    				"firstBlockHeight": 963510,
    				"lastTxid": "0460fc1a1ada6479037a07c05509cfcb0d2e8ead2d2b32a5a6784f558c448866",
    				"lastTimestamp": 1636526891,
    				"lastBlockHeight": 963512,
    				"tCdd": 12300000,
    				"tRate": 4.65,
    				"status": 1
    			},
    			{
    				"pid": "33333000000002222222222",
    				"type": "FEIP",
    				"sn": "6",
    				"ver": "1",
    				"name": "Master",
    				"lang": "en-US",
    				"title": "FEIP6V1_Master(en-US)",
    				"desc": "An address authorize another address as its master.",
    				"authors": "C_armX",
    				"prePid": "",
    				"fileUrl": "https://bbs.cash/topic/565/feip6v6_master-en-us",
    				"signer": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"firstTxid": "3333300000000000111111111111111111111111222222222222222222233333",
    				"firstTimestamp": 1619261292,
    				"firstBlockHeight": 963600,
    				"lastTxid": "3333300000000000111111111111111111111111222222222222222222233333",
    				"lastTimestamp": 1619261292,
    				"lastBlockHeight": 963612,
    				"tCdd": 221800,
    				"tRate": 4.12,
    				"status": 1
    			}
    		],
    		"total": 2,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    getProtocolOpHistory

    查询除data.op值为“rate”之外的协议链上操作历史信息。

    url

    [服务方发布的urlMainPart]apip5/v1/

    示例:

    https://www.sign.cash/api/apip5/v1/

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询PID为"222220000000000011111111111111"的协议操作记录,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip7/v1/getProtocolOpHistory",
    	"query": {
    		"term": {
    			"pid": "222220000000000011111111111111"
    		}
    	},
    	"sort": [{
    		"txTimestamp": {
    			"order": "desc"
    		}
    	}],
    	"from": 0,
    	"size": 20,
    	"sign": ""
    }
    

    响应参数

    通用参数参见通用响应方式。本接口响应参数:

    • data
    name type description requested
    list object See below
    total uint The total number of items. Y
    bestHeight uint The latest block height when getting the data. Y
    • data.list
    name type description
    pid string The ID of the protocol,that is,the double sha256 value of the protocol file.
    op string The operation, "register", "unregister", or "update".
    type string The type of the protocol, such as"FEIP".
    sn string The serial number in this type of protocol.
    ver string The version of the protocol.
    name string The name of the protocol.
    lang string The language of the protocol being registered, formatted with i18n(internationalization), such as "en-US".
    desc string Thedescriptionoftheprotocol.
    authors string The authors of the protocol.
    prePid string Double sha256 value of the previous version protocol file.
    fileUrl string array Locations to find the protocol file.
    signer string The signer of the first input of the transaction in which the protocol was first published.
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    blockHeight uint The height of the block where the transaction is written
    • 示例

    响应PID为"222220000000000011111111111111"的协议操作记录,按交易时间戳倒序,第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    				"pid": "222220000000000011111111111111",
    				"op": "update",
    				"type": "FEIP",
    				"sn": "6",
    				"ver": "1",
    				"name": "Master",
    				"lang": "en-US",
    				"desc": "Define the Master.",
    				"authors": "C_armX",
    				"prePid": "24234343333",
    				"fileUrl": "https://bbs.cash/topic/565/",
    				"signer": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"txTimestamp": 1613211239,
    				"txid": "0460fc1a1ada6479037a07c05509cfcb0d2e8ead2d2b32a5a6784f558c448866",
    				"blockHeight": 989239
    
    			},
    			{
    				"pid": "222220000000000011111111111111",
    				"op": "register",
    				"type": "FEIP",
    				"sn": "6",
    				"ver": "1",
    				"name": "Master",
    				"lang": "en-US",
    				"desc": "An address authorize another address as its master.",
    				"authors": "C_armX",
    				"prePid": "",
    				"fileUrl": "https://bbs.cash/topic/565/feip6v6_master-en-us",
    				"signer": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"txTimestamp": 1610261291,
    				"txid": "3333333333333333333333333333388888888888888888888888888889",
    				"blockHeight": 989021
    			}
    		],
    		"total": 2,
    		"bestHeight": 993667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    getProtocolRateList

    说明

    查询对协议的链上评价信息,即data.op值为“rate”的记录。

    url

    [服务方发布的urlMainPart]apip5/v1/getProtocolRateList

    示例:

    https://www.sign.cash/api/apip5/v1/getProtocolRateList

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询pid为"0000000011111111111111111111111222"的协议的币天销毁大于等于1000的评分记录,按“rate”一级降序,交易时间二级降序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip7/v1/getRateHistory",
    	"query": {
    		"bool": {
    			"must": [{
    					"term": {
    						"pid": ""0000000011111111111111111111111222""
    					}
    				},
    				{
    					"range": {
    						"cdd": {
    							"gte": 1000
    						}
    					}
    				}
    			]
    		}
    	},
    	"sort": [{
    		"rate": {
    			"order": "desc"
    		},
    		{"txTimeStamp": {
    			"order": "desc"
    		}
    	}],
    	"from": 0,
    	"size": 20,
    	"sign": ""
    }
    

    响应参数

    通用参数参见通用响应方式。本接口响应参数:

    • data
    name type description requested
    list object See below
    total uint The total number of items. Y
    bestHeight uint The latest block height when getting the data. Y
    • data.list
    name type description
    pid string The ID of the protocol,that is,the double sha256 value of the protocol file.
    rater uint The address of the first input of the rating transaction
    rate uint
    cdd uint64
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    blockHeight uint The height of the block where the transaction is written
    • 示例

    响应pid为"0000000011111111111111111111111222"的协议的币天销毁大于等于1000的评分记录,按“rate”一级降序,交易时间二级降序,第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    				"pid": "0000000011111111111111111111111222",
    				"rater": "FS2AWq1dgdhCpNTwqfBbMBBJGNNj1LSboy",
    				"rate": 5,
    				"cdd": 3100,
    				"txid": "0460fc1a1ada6479037a07c05509cfcb0d2e8ead2d2b32a5a6784f558c448866",
    				"txTimestamp": 1618832997321,
    				"blockHeight": 989302
    			},
    			{
    				"pid": "0000000011111111111111111111111222",
    				"rater": "FLx88wdsbLQyZRmbqtpeXA9u5FG9EyCash",
    				"rate": 4,
    				"cdd": 10000,
    				"txid": "dde54b27326c11236676dfd5b3c030539a72e39924e7ad835b70ff16a5647715",
    				"txTimestamp": 1618834297302,
    				"blockHeight": 989302
    			}
    
    		],
    		"total": 2,
    		"bestHeight": 993667
    	},
    	"sign": ""
    }
    
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


Log in to reply