APIP1V1_OpenAPI(zh-CN)

昌用

APIP1: OpenAPI
Version: 1
Language: zh-CN
Author: C_armX, Write_cash
Status: draft
Created date: 2021-10-30
Update:2022-04-26
PID: ""
TXID:

APIP1V1_OpenAPI(zh-CN)

关于APIP

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

APIP协议的发布

APIP协议与自由共识生态的其他自由协议一样，由协议作者按照《FEIP1_FreeProtocol》协议在链上发布注册，注册交易的OP_RETURN内容为：

{
    "type": "FEIP"
    "sn": 1,
    "ver": 7,
    "name": "FreeProtocol",
    "pid": [string, FEIP1V7 协议文本的双sha256哈希值，该协议正式发布前暂时留空],
    "data": {
        "op": "register",
        "type": "APIP",
        "sn": [int,协议编号，必填],
        "ver": [int,协议版本号，必填],
        "name": [string，协议名称，必填],
        "desc": [string,对协议的描述],
        "authors": [string array, 作者们的fch地址],
        "pid": [string, 协议id，即协议文本的双sha256哈希值，留空为测试中协议]，
        "lang": [string，语言，基于i18n编码],
        "prePid": [string，前一版本协议文本的pid],
        "fileUrl": [string array, 协议文本存放位置]
    }
}

自由协议的更新、注销和评价参见《FEIP1_FreeProtocol》。

接口标识

唯一标识

接口名称@PID#[所属APIP协议的PID]

简化标识

接口名称@协议类型+协议编号

简化标识不一定唯一，主要便于人类记忆和识别，重要场景或机器识别应采用唯一标识。

示例：

APIP1的balance接口的唯一标识为：balance@PID#[APIP1协议文本的哈希值，待确认]

简化标识为：balance@APIP1。

接口url的构成

接口的url分为两部分：urlMainPart和urlSubPart。

urlMainPart

urlMainPart为某API服务方提供的所有接口url的共同部分，由服务方依据《FEIP29_Service》在data.params.urlMainPart字段中发布在链上。格式为：

scheme://domain or IP:port/subdirectory/

所需信息	必填	说明
scheme	Y	协议类型，http、https、ws等
domainOrIP	Y	域名或IP
port	N	端口
subdirectory	N	接口子目录

示例

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

urlSubPart

urlSubPart是该API服务方按照APIP协议，在链上发布API服务时声明的具体接口的具体位置。格式为：

apip[协议编号]/v[版本号]/[接口名称]

示例：

apip1/v1/connect

url

接口的完整url = urlMainPart + urlSubPart

示例：

https://www.sign.cash/api/apip1/v1/connect

时间戳格式

APIP协议涉及的时间戳，若无特定说明，默认为13位，精确到毫秒。

密码算法

哈希算法

无特殊说明，哈希算法采用两次sha256算法，即:sha256(sha256([message]))，哈希值为十六进制，字母为小写.

加密算法

无特殊说明，文本和文件加解密采用ECC256k1-AESCBC算法，协议PID为[待开发完成后发布]。

签名算法

对称密码签名：无特殊说明，对称密码签名验证采用加入symKey做两次sha256哈希算法进行签名。
非对称密码签名：无特殊说明，非对称密码签名验证采用椭圆曲线算法（ECDSA）算法，协议PID为[待开发完成后发布]。

示例身份信息

APIP协议默认采用以下请求方身份信息:

requester：FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

requester的公钥pubKey：030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

requester的私钥priKey：L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

requester获得的对称密钥symKey：d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

API服务流程

按照APIP协议，服务方（API服务的提供者，简称APISP）为请求方（API服务的使用者，APP或用户个人）提供API服务的一般流程为：

服务方开发部署API服务

服务方选择一个或多个链上注册的APIP协议，开发和部署相应的API服务。

服务方链上注册API服务

服务方依据《FEIP29_Service》协议，在链上发布自己的API服务，并给出订购方式、API的urlMainPart。

发布者FCH地址为交易的第一个输入，发布交易的OP_RETURN内容为：

{
    "type": "FEIP",
    "sn": 29,
    "ver": 2,
    "name": "Service",
    "pid": [string, FEIP29V1 协议文本的双sha256哈希值，该协议正式发布前暂时留空],
    "data":{
        "op": "start",
        "stdName": [string，服务的英文名],
        "localName": [string array，服务的其他语言名称],
        "desc": [string, 对服务的描述，包括：url共用部分，付费方式，服务价格等],
        "type": [string array, 服务的分类，可多个。应包含“APIP”]
        "prot": [string array, 所遵循的协议]
        "urlHead": [string, API的url的首部]
        "pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
        "params":{
	        "urlMainPart": [string, API访问位置的共同部分，如http://sign.cash/api/],
	        "receivingAccount":[string,收款账号，缺省为发布者FCH'地址],
	        "pricePerRequest": [int, 每次请求的服务收费，采用最小单位],
	        "minPayment": [int64, 最低单次购买金额，采用最小单位],
	        "currency": [string，支付的币种，缺省为FCH，法币则遵循ISO4217，如'CNY']
    }
}

请求方链上查询API服务

请求方在链上查询自己所需要的API服务方，获得订购方式（receivingAccount，pricePerRequest，minPayment，currency）和API路径的共同部分（urlMainPart）。

请求方链下订购API服务

请求方按照订购方式，向服务方订购API服务。服务方记录请求方的身份（FCH地址）和充值余额，开始服务。

请求方发出连接服务请求

请求方通过connect接口，向服务方发起包含自身pubKey的连接请求和私钥签名，以获得后续数据请求使用的对称密钥symKey，详情参见[##connect接口](##connect接口）。

服务方验证请求分配密钥

服务方对请求进行安全验证后，发放用请求方pubKey加密的对称密钥symKey。具有相同urlMainPart的接口共用同一个symKey。

请求方解密保存symKey

请求方用自己的私钥priKey解密密文，获得symKey，保存用于后续数据请求。

1-7步骤的流程图：

APIP1_OpenAPI插图连接.png

请求方发出数据服务请求

请求方根据自身数据需求，选择服务方的对应接口，构造API的url和请求参数并签名后，向服务方发出数据请求。详情参见[##数据服务接口](##数据服务接口）

服务方验证请求返回数据

服务方收到请求后，进行安全验证无误后，返回响应数据和签名给请求方。

请求方验证签名接受数据

请求方收到响应数据后，验证签名是否无误则接受数据，服务完成。

8-10的流程图：

谁是API的请求方

APP有两种请求方设定逻辑：

1.用户作为请求方

1）用户通过APP或其他途径用自己的FCH地址购买服务。
2）用户进入APP需要获取数据时，用自己的私钥签名发起connect连接请求。
3）APP为用户在本地保存symKey，用于向API服务方发起数据请求。
4）特点：符合密码经济中“用户掌握数据”的安全准则，减少对APP的依赖，更加安全、开放、去中心化。

2.APP作为请求方

1）APP发布者用自己的地址向API服务方购买服务，获得symKey。
2）用户使用APP时，所需要的数据由APP向API服务方提出请求。
3）特点：符合传统开发习惯，便于APP运营者掌控数据，有中心化风险。

如何购买API服务

请求方购买API服务的方式由服务方在链上注册服务时，在data.desc字段描述，在data.params字段给出相关参数。服务方未特殊声明，则默认采用以下方式：

服务方链上注册服务时在data.params中声明收费信息

{
    "receivingAccount":[string,收款账号，缺省为发布者FCH'地址],
    "pricePerRequest": [int, 每次请求的服务收费，采用最小单位],
    "minPayment": [int64, 最低单次购买金额，采用最小单位],
    "currency": [string，支付的币种，缺省为FCH，法币则遵循ISO4217，如'CNY']
}

请求方链上获取收费信息的两种方式
- 1）通过APP获取。APP提供API服务方及价格列表，供请求方选择购买服务。
- 2）请求方自行查找链上API服务方，获取API服务的收费信息。
请求方链上购买服务的两种方式
- 1）通过APP购买。APP在请求方同意购买，并填写或选择支付金额后，为请求方构造包含购买标记的交易，由请求方确认后发送交易。
- 1. 请求方自行构造包含购买标记的交易完成支付。
请求方的购买标记，即购买交易的OP_RETURN内容，如下：

{
    "type": "APIP"
    "sn": 1,
    "ver": 1,
    "name": "OpenAPI",
    "pid": [string, FEIP1V7 协议文本的双sha256哈希值，该协议正式发布前暂时留空],
    "data": {
        "op":"buy",
        "sid":[string，所购买服务的sid，必填]
    }
}

API服务方启动服务
- API服务方收到有购买标记的交易后，自动登记第一个输入的FCH地址为用户ID，并登记余额，开始服务。
- 请求方的每次请求按pricePerRequest计减余额。
- 余额一旦小于pricePerRequest则服务终止，删除该用户信息，以防止用户信息累计过多，并防止与此相关的攻击。

connect接口

connect接口用来向服务方申请获得symKey，symKey用于后续数据请求的签名和验证。

1. 接口名称

connect

2. 请求方法

POST

3. URL

url = urlMainPart + urlSubPart

= [服务方链上注册服务时的data.params.urlMainPart值] + "apip1/v1/connect"

示例:

data.params.urlMainPart = "https://www.sign.cash/api/"

url: "https://www.sign.cash/api/apip1/v1/connect"

4. 请求参数

参数	类型	说明	必填
pubKey	hex	请求方的公钥，用于验证身份和授权	Y
url	string	当前connect的url，防止重放攻击	Y
timestamp	time stamp	精确到毫秒的时间戳，防止重放攻击	Y
sign	string	用请求方私钥priKey对压缩升序后的其他参数的签名，防止身份伪造	Y

签名

请求方用自己的私钥priKey对除sign之外的请求参数压缩升序后，进行签名，得到sign。

示例

请求参数

{
	"pubKey": "030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a",
	"url": "https://www.sign.cash/api/apip1/v1/connect",
	"timestamp": 1635513688254,
    "sign": "H6d+wvrsj5Bgh4Y2GeOFujYvXijMK1FG97bSDd7zaX8VY78X3a2Ey2Success.wpyo5ASiwWA8cW6gP1rejWjZMbPcS3k\u003d"
}

其中，sign为私钥priKey（L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8）对压缩排序后的其他请求参数（{"pubKey":"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a","timestamp":"1635513688254","url":"https://www.sign.cash/api/apip1/v1/connect"}）所做的签名。

请求方保存API服务信息

请求方为其使用的每个APIP协议，分别保存以下信息：

信息名称	类型	说明	必填
sid	string	接口服务的SID，即服务方在链上注册服务时的txid	N
pid	string	APIP协议的PID	N
title	string	APIP协议的标题，如：APIP1V1_OpenAPI(zh-CN)	N
sn	int	APIP协议编号	Y
ver	int	APIP协议版本号	Y
sid	string	当前接口服务的SID，即服务方在链上注册服务时的txid	N
stdName	string	接口服务链上注册的英文标准名称	N
urlMainPart	string	connect的urlMainPart，相同sid的urlMainPart值相同	Y
pubKeyAdmin	string	发布者为api服务指定的管理员pubKey，用于加密和验证签名，缺省为服务发布者公钥	N
addressAdmin	string	发布者为api服务指定的管理员,即pubKeyAdmin计算的FCH地址，缺省为服务发布者地址	N
receivingAccount	string	服务方链上发布的充值收款账号，缺省为发布者FCH地址	N
pricePerRequst	string	每次请求的服务收费，采用最小单位	N
minPayment	string	最低单次购买金额，采用最小单位	N
currency	string	支付的币种，缺省为FCH，法币则遵循ISO4217，如'CNY'	N
symKey	string	当前生效的symKey，相同urlMainPart的各接口使用同一个symKey	N
timestamp	time stamp	当前生效的symKey获得的时间戳	N
days	int	当前生效的symKey的有效天数	N
apiBalance	int64	请求方当前服务余额	all

5. 响应

验证请求。服务方对请求依次验证：
- 1）验证用户。验证requester是否在用户列表中，用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000.
- 2）验证请求对象。验证签名内容中的“url”值是否与服务方当前接口的url相同，防止重放攻击。不同则返回1001
- 3）验证时间戳。验证当前时间戳减timestamp的绝对值是否小于服务方设定的windowTime。过期返回1002.
- 4）验证签名：用pubKey验证签名sign是否正确，防止身份伪造。失败返回1003。
响应状态

code	message	说明	响应参数
0	Success.	请求成功.返回数据和签名	data，apiBalance
1000	Please purchase the service.	请购买该服务。返回购买信息	receivingAccount, pricePerRequst, minPayment, currency
1001	The URL you requested is wrong.	请求中的url与服务方接口url不符，返回服务方接口url	url
1002	Request expired，	请求已过期。返回服务方设定的时间窗口长度。	windowTime
1003	Failed to verify signature.	验证签名失败
1006	Other error，please contact the service provider.	其他错误，请联系服务方.
1020~1099		API服务商自定义响应码、响应信息和响应参数

响应参数

参数	类型	说明	适用状态
code	int	响应状态码	all
message	string	响应状态描述	all
data.symKeyEncrypted	string	symKey的密文	0
data.days	int	symKey的有效天数	0
data.receivingAccount	string	服务方链上发布的充值收款地址，缺省为服务发布者地址	1000
data.pricePerRequst	string	服务方每次请求价格	1000
data.minPayment	string	服务方最低充值金额	1000
data.currency	string	充值币种，缺省为"FCH"，法币则遵循ISO4217	1000
data.url	string	服务方当前接口的url	1001
data.windowTime	timestamp	服务方设置的时间窗口长度，精确到毫秒	1002
apiBalance	int64	请求方当前服务余额	all

示例

设服务方验证请求无误后，为该请求方分配symKey为："d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"。

请求方公钥pubKey为："030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a"。

则响应参数为：

{
	"code": "0",
	"message": "Success.",
	"data": {
		"symKeyEncrypted": "A+wCC1gjAoWiF+it5xnE668eoJHHMnF5UpjI2fxKQeuJyOWAiFsl5RPX0HEIEPm5ygmOifwBpZ2Yh3e5NyH2BlDEPaYPFoUZqdedBTRWoVHR48hKFN088dZYX+/6f0w+jhOsjxylXlxdwe6p/kwXNIuQ3iEVPz9cyVGNdFm8vVMQkHtbZlIdDjj0L13CCOuIJnByjNBMsPbP4qCnNSunuAIV91z2XAGlofGrIozGA3AY",
		"days": 365
	},
	"apiBalance": 2000
}

服务方应保存的用户信息

名称	类型	说明
address	string	用户的FCH地址，即ID，应与充值FCH地址、connect请求参数中pubKey计算的FCH地址相同。
apiBalance	int64	用户余额，余额小于pricePerRequest值，则删除该用户所有信息，充值后重建用户信息
pubKey	string	用户的公钥，connect请求时获取，用于验证connect请求的签名。若对应FCH地址未保存，则视为新用户。
symKey	string	该用户最新的symKey，过期保留直至用户重置
timestamp	int	当前symKey发放时间，用于控制连接的有效期
days	int	N

数据请求接口

1. 接口名称

接口名称在相应APIP协议中定义。

示例：

在协议APIP99V1中定义接口 interface1

2. 请求方法

POST

3. URL

url = urlMainPart + urlSubPart

urlMainPart为 [服务方链上注册服务时的data.params.urlMainPart值],如："https://www.sign.cash/api/"

urlSubPart在具体的APIP协议的具体接口处定义，格式为：apip[协议编号]/v[协议版本号]/[接口名称]。如："apip99/v1/interface1"

示例:

urlMainPart = "https://www.sign.cash/api/"

urlSubPart = "apip99/v1/interface1"

url: "https://www.sign.cash/api/apip99/v1/interface1"

4. 请求参数

请求应包含以下通用参数：

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

query、sort、from和size由具体APIP协议规定。

签名

将symKey加入除sign以外的其他请求参数并压缩升序后，做两次sha256计算，获得sign。

示例：

查询address包含“armX”，且1000<amount<=2000的条目，按amount升序排列，取前20条。

请求参数：

{
	"requester": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
	"timestamp": 1635513688254,
	"url": "https://www.sign.cash/api/interface1",
	"query": {
		"bool": {
			"must": {
				"match": {
					"address": "armX"
				},
				"range": {
					"amount": {
						"gt": 1000,
						"lte": 2000
					}
				}
			}
		}
	},
	"sort": [{
		"amount": {
			"order": "asc"
		}
	}],
	"from": 0,
	"size": 20,
	"sign": "814b7ab051e0d4141129b7ae6e884d17e8c78c0afe91cef5790d51c0241a0d40"
}

其中：

sign =

sha256(sha256({"from":0,"query":{"bool":{"must":{"match":{"address":"armX"},"range":{"amount":{"gt":1000,"lte":2000}}}}},"requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","size":20,"sort":[{"amount":{"order":"asc"}}],"symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09","timestamp":"1635513688254","url":"https://www.sign.cash/api/interface1"}))

=814b7ab051e0d4141129b7ae6e884d17e8c78c0afe91cef5790d51c0241a0d40

5. 响应

验证请求：服务方按顺序验证请求
- 1）验证用户。验证requester是否在用户列表中，用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000。
- 2）验证请求对象。验证签名内容中的url值是否与服务方当前接口的url相同，防止重放攻击。不同则返回1001。
- 3）验证时间戳。验证当前时间戳减请求参数中timestamp的绝对值是否小于服务方设定的windowTime，防止重放攻击。过期返回1002.
- 4）验证symKey时效。检查服务器保存的requeter的symKey是否过期。过期返回1004.
- 5）验证签名。在请求参数中加入requester的symKey做两次sha256哈希，验证值是否与sign的值一致。不一致返回1003。
响应状态

code	message	说明	响应参数
0	Success.	请求成功.返回数据和签名	data, apiBalance
1000	Please purchase the service.	请购买该服务。返回购买信息	receivingAccount, pricePerRequst, minPayment, currency
1001	The URL you requested is wrong.	请求中的url与服务方接口url不符，返回服务方接口url	url
1002	Request expired，	请求已过期。返回服务方设定的时间窗口长度。	windowTime
1003	Failed to verify signature.	验证签名失败
1004	The symKey has expired, please connect again.	symKey过期，请重新连接
1005	Too much data requested.	请求数据太多。返回最大请求数量。	maxSize
1006	No data meeting the conditions.	没查到符合条件的数据
1007	Other error，please contact the service provider.	其他错误，请联系服务方.
2000~		API服务商自定义响应码、响应信息和响应参数.

响应参数

参数	类型	说明	适用状态
code	int	响应状态码	all
message	string	响应状态描述	all
data	object	正常返回非列表数据，由具体APIP定义	0
data.receivingAccount	string	1000状态，服务方链上发布的充值收款地址，缺省为服务发布者地址	1000
data.pricePerRequst	string	服务方每次请求价格	1000
data.minPayment	string	服务方最低充值金额	1000
data.currency	string	充值币种，缺省为"FCH"，法币则遵循ISO4217	1000
data.url	string	服务方当前接口的url	1001
data.windowTime	timestamp	服务方设置的时间窗口长度，精确到毫秒	1002
data.maxSize	int	服务方设定的最大响应数量	1005
apiBalance	int64	请求方当前服务余额	all
sign	string	将symKey加入响应参数做两次sha256哈希的签名值	all

示例

{
	"code": "0",
	"message": "Success.",
	"data": {
		"total": 3,
		"p0": [{
			"p3": 3,
			"p4": "c",
			"p5": "BBBBB"
		}, {
			"p3": 5,
			"p4": "b",
			"p5": "CCCCC"
		}, {
			"p3": 4,
			"p4": "a",
			"p5": "aaaaa"
		}],
		"bestHeight": 100
	},
	"apiBalance": 55000,
	"sign": "2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816"
}

其中

sign=

sha256(sha256({"apiBalance":55000,"code":"0","data":{"bestHeight":100,"p0":[{"p3":3,"p4":"c","p5":"BBBBB"},{"p3":5,"p4":"b","p5":"CCCCC"},{"p3":4,"p4":"a","p5":"aaaaa"}],"total":3},"message":"Success.","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))

= 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816

6. 请求方验证响应数据

请求方收到数据后，取出sign，加入symKey压缩升序后，做两次sha256哈希，与sign值相比较，一致则接受数据。以防止中间人攻击。

7. 请求方重置symKey

请求方在1）希望重置symKey，或2）收到错误码1004，symKey过期时，或3）收到错误码1000，并完成充值时，用connect接口申请新的symKey。

APIP简易查询语法

本语法参考Elasticsearch的Query DSL，根据APIP数据情况，选用部分语法。

查询条件在query字段给出，排序条件在sort字段给出。

match_all（获取所有）

{
	"query": {
		"match_all": {}
	}
}

请求所有条目。

term(精确匹配）

{
	"query": {
		"term": {
			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"
		}
	}
} //查询address为“FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX”的项目。

terms(多项精确匹配）

{
	"query": {
		"terms": {
			"address": [
				"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX", "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK"
			]
		}
	}
} //查询address为“FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX”或“FEk41Kqjar45fLDriztUDTUkdki7mmcjWK”的项目。

match（单字段匹配）

对单个字段进行查询，对字符串字段为模糊查询，对非字符串字段为精确匹配查询。

字符串模糊查询：

{
	"query": {
		"match": {
			"address": {
				"query": "armX cash",
				"operator": "and"
			}
		}
	}
} //查询address中同时包含“armX”和“cash”的项目。其中”operator“缺省为“or“，见下例。

{
	"query": {
		"match": {
			"address": "armX cash"
			}
		}
	}
} //查询address中同时包含“armX”或“cash”的项目。

非字符串精确匹配查询：

{
	"query": {
		"match": {
				"amount": 3000
			}
		}
	}
}//查询amount=3000的项目。

multi_match（多字段匹配）

单个条件在多个字段查询。query为查询内容，fields给出查询的各字段。

{
  "query": {
    "multi_match": {
      "query": "armX",
      "fields": [
        "address",
        "cid"
      ]
    }
  }
} //在address和cid两个字段查询包含“armX”的项目。

range（范围查询）

范围查询,用于在单个字段查询某一范围内的数值型、日期类型或者字符串型字段。参数为：

gt 大于，查询范围的最小值，也就是下界，但是不包含临界值。
gte 大于等于，和 gt 的区别在于包含临界值。
lt 小于，查询范围的最大值，也就是上界，但是不包含临界值。
lte 小于等于，和 lt 的区别在于包含临界值。

{
  "query": {
    "range": {
      "amount": {
        "gt": 3000,
        "lte": 10000
      }
    }
  }
}//查询amount值大于3000，小于等于10000的项目。

exists（非空查询）

非空查询。查询单个字段，值不为空的项目。field指定查询字段。

{
  "query": {
    "exists": {
      "field": "user"
    }
  }
}

bool（复合查询）

复合查询。组合多个查询条件进行查询。组合方式为：

must：必须满足所有子句条件，相当于and。
must_not：必须不匹配所有子句条件。
should：可满足多个子句条件的任一个，相当于or，需单独使用，或嵌套在must+bool内使用。

match、multi_match、range、exists只能作为子句出现在must、must_not、should中。

一个bool结构中可包含多个组合方式，一个组合方式可包含多个条件。

示例：

{
	"query": {
		"bool": {
			"must": [{
					"bool": {
						"should": [{
								"match": {
									"type": "cloud drive"
								}
							},
							{
								"match": {
									"desc": "cash address"
									}
								}
							}
						]
					}
				},
				{
					"range": {
						"amount": {
							"gte": 3000
						}
					}
				}
			],
			"must_not": {
				"match": {
					"address": "armX"
				}
			}
		}
	}
}//查询type包含”cloud“或“drive”，或desc包含”cash”和“address“，且amount大于等于3000，且address不包含”armX“的项目。

为空查询

用bool+must_not+exists组合实现为空查询。示例：

{
    "query": {
        "bool": {
            "must_not": {
                "exists": {
                    "field": "opReturn"
                }
            }
        }
    }
} //查询opReturn字段为空的项目。

排序

用sort对象实现多级排序，order指定排序方式，asc为升序，desc为倒序。示例：

{
	"sort": [{
			"amount": {
				"order": "desc"
			}
		},
		{
			"index": {
				"order": "asc"
			}
		}
	]
} //以cd降序为一级，amount字段做升序为二级做排序。

分页

以from和size实现分页。from给出开始序号（初始值为0），size给出请求数量。

响应参数包含total字段给出命中的项目总数。

示例：

{
	"from": 0,
	"size": 20,
	"query": {
		"match": {
			"address": "armX"
		}
	},
	"sort": {
		"amount": {
			"order": "asc"
		}
	}
} //查询address包含“armX”的项目，按amount值升序，从首个开始取20个项目。

水雷_zzHe

@昌用 sign=sha256(sha256({"txid":"df0e4393e103fd8692165c9eb74dd25b8dae662dbce926bf824237a55d4b61d3","index":1,"secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"})=c4f3f458f00c7915ebbf463fe99881dd7f7fe9d1106479222771b8cd8fa7b1a5
上面这个示例的括号有缺失吧？

昌用

是的，少了个），加上了。

APIP1V1_OpenAPI(zh-CN)

APIP1V1_OpenAPI(zh-CN)

目录

关于APIP

APIP协议的发布

接口标识

接口url的构成

时间戳格式

密码算法

哈希算法

加密算法

签名算法

示例身份信息

API服务流程

谁是API的请求方

1.用户作为请求方

2.APP作为请求方

如何购买API服务

connect接口

1. 接口名称

2. 请求方法

3. URL

4. 请求参数

请求方保存API服务信息

5. 响应

服务方应保存的用户信息

数据请求接口

1. 接口名称

2. 请求方法

3. URL

4. 请求参数

5. 响应

6. 请求方验证响应数据

7. 请求方重置symKey

APIP简易查询语法