APIP1: OpenAPI
Version: 1
Language: zh-CN
Author: C_armX, Write_cash
Status: draft
Created date: 2021-10-30
Update:2022-12-01
PID: ""
TXID:
APIP1V1_OpenAPI(zh-CN)
目录
关于APIP
APIP的发布
接口标识
接口url的构成
时间戳格式
密码算法
示例身份信息
API服务流程
谁是API的请求方
如何购买API服务
connect接口
数据请求接口
APIP简易查询语法
Type: APIP
SerialNumber: 1
ProtocolName: OpenAPI
Version: 1
Description : 定义在Freecash主链上发布开放API协议的一般方式.
Author: C_armX,Write_cash
Language: zh-CN
PID:""
关于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分为两部分：urlHead和urlTail。
- urlHead
urlHead为某API服务方提供的所有接口url的共同部分，由服务方依据《FEIP29_Service》在data.params.urlHead字段中发布在链上。格式为：
scheme://domain or IP:port/subdirectory/
| 所需信息 |
必填 |
说明 |
| scheme |
Y |
协议类型，http、https、ws等 |
| domainOrIP |
Y |
域名或IP |
| port |
N |
端口 |
| subdirectory |
N |
接口子目录 |
示例
https://www.sign.cash/api/
- urlTail
urlTail是该API服务方按照APIP协议，在链上发布API服务时声明的具体接口的具体位置。格式为：
apip[协议编号]/v[版本号]/[接口名称]
示例：
apip1/v1/connect
- url
接口的完整url = urlHead + urlTail
示例：
https://www.sign.cash/api/apip1/v1/connect
时间戳格式
APIP协议涉及的时间戳，若无特定说明，默认为13位，精确到毫秒。
来自Freecash区块数据的时间戳为10位。
密码算法
哈希算法
无特殊说明，哈希算法采用两次sha256算法，即:sha256(sha256(byte[] message_bytes))，哈希值为Hex，字母为小写.
加密算法
无特殊说明，文本和文件加解密采用ECC256k1-AESCBC算法，协议PID为[待开发完成后发布]。
签名算法
-
对称密码签名：无特殊说明，对称密码签名验证采用数据加入sessionKey后序列化，做两次sha256哈希算法得到签名。
-
非对称密码签名：无特殊说明，非对称密码签名验证采用椭圆曲线算法（ECDSA）算法，以签发者私钥对数据进行签名，协议PID为[待开发完成后发布]。
示例身份信息
APIP协议默认采用以下请求方身份信息:
requester：FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
requester的公钥pubKey：030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
requester的私钥priKey：L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
requester获得的对称密钥sessionKey：d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
API服务流程
按照APIP协议，服务方（API服务的提供者，简称APISP）为请求方（API服务的使用者，APP或用户个人）提供API服务的一般流程为：
- 服务方 开发部署API服务
服务方选择一个或多个链上注册的APIP协议，开发和部署相应的API服务。
- 服务方 链上注册API服务
服务方依据《FEIP29_Service》协议，在链上发布自己的API服务，并给出订购方式、API的urlHead。
发布者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”]
"protocols": [string array, 所遵循的协议]
"urls": [string array, API的url的首部]
"pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
"params":{
"urlHead": [string, API访问位置的共同部分，如http://sign.cash/api/],
"account":[string,收款账号，缺省为发布者FCH'地址],
"currency": [string，支付的币种，缺省为FCH，法币则遵循ISO4217，如'CNY'],
"pricePerRequest": [float, 每次请求的服务收费，采用选用货币的标准单位],
"minPayment": [float, 最低单次购买金额，采用选用货币的标准单位]
}
}
- 请求方 链上查询API服务
请求方在链上查询自己所需要的API服务方，获得订购方式（receivingAccount，pricePerRequest，minPayment，currency）和API路径的共同部分（urlHead）。
- 请求方 链下订购API服务
请求方按照订购方式，向服务方订购API服务。服务方记录请求方的身份（FCH地址）和充值余额，开始服务。
- 请求方 发出连接服务请求
请求方通过connect接口，向服务方发起包含自身pubKey的连接请求和私钥签名，以获得后续数据请求使用的对称密钥sessionKey，详情参见[##connect接口](##connect接口）。
- 服务方 验证请求分配密钥
服务方对请求进行安全验证后，发放用请求方pubKey加密的对称密钥sessionKey。具有相同urlHead的接口共用同一个sessionKey。
- 请求方 解密保存sessionKey
请求方用自己的私钥priKey解密密文，获得sessionKey，保存用于后续数据请求。
1-7步骤的流程图：
- 请求方 发出数据服务请求
请求方根据自身数据需求，选择服务方的对应接口，构造API的url和请求参数并签名后，向服务方发出数据请求。详情参见[##数据服务接口](##数据服务接口）
- 服务方 验证请求返回数据
服务方收到请求后，进行安全验证无误后，返回响应数据和签名给请求方。
- 请求方 验证签名接受数据
请求方收到响应数据后，验证签名是否无误则接受数据，服务完成。
8-10的流程图：
谁是API的请求方
APP有两种请求方设定逻辑：
1.用户作为请求方
-
1）用户通过APP或其他途径用自己的FCH地址购买服务。
-
2）用户进入APP需要获取数据时，用自己的私钥签名发起connect连接请求。
-
3）APP为用户在本地保存sessionKey，用于向API服务方发起数据请求。
-
4）特点：符合密码经济中“用户掌握数据”的安全准则，减少对APP的依赖，更加安全、开放、去中心化。
2.APP作为请求方
-
1）APP发布者用自己的地址向API服务方购买服务，获得sessionKey。
-
2）用户使用APP时，所需要的数据由APP向API服务方提出请求。
-
3）特点：符合传统开发习惯，便于APP运营者掌控数据，有中心化风险。
如何购买API服务
请求方购买API服务的方式由服务方在链上注册服务时，在data.desc字段描述，在data.params字段给出相关参数。服务方未特殊声明，则默认采用以下方式：
- 服务方链上注册服务时在data.params中声明收费信息
{
"urlHead": [string, API访问位置的共同部分，如http://sign.cash/api/],
"account":[string,收款账号，缺省为发布者FCH'地址],
"currency": [string，支付的币种，缺省为FCH，法币则遵循ISO4217，如'CNY'],
"pricePerRequest": [float, 每次请求的服务收费，采用选用货币的标准单位],
"minPayment": [float, 最低单次购买金额，采用选用货币的标准单位]
}
-
请求方链上获取收费信息的两种方式
-
请求方链上购买服务的两种方式
-
请求方的购买标记，即购买交易的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接口用来向服务方申请获得sessionKey，sessionKey用于后续数据请求的签名和验证。
1. 接口名称
connect
2. 请求方法
POST
3. URL
url = urlHead + urlTail
= [服务方链上注册服务时的data.params.urlHead值] + "apip1/v1/connect"
示例:
data.params.urlHead = "https://www.sign.cash/api/"
url: "https://www.sign.cash/api/apip1/v1/connect"
4. 请求参数
| 参数 |
类型 |
说明 |
必填 |
| pubKey |
hex |
请求方的公钥，用于验证身份和授权 |
Y |
| url |
string |
当前connect的url，防止重放攻击 |
Y |
| time |
time stamp |
精确到毫秒的时间戳，防止重放攻击 |
Y |
| sign |
string |
用请求方私钥priKey对序列化后的其他参数的签名，防止身份伪造 |
Y |
请求方用自己的私钥priKey对除sign之外的请求参数序列化后，进行签名，得到sign，加入请求json。
请求参数
{
"pubKey": "030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a",
"url": "https://www.sign.cash/api/apip1/v1/connect",
"time": 1635513688254,
"sign": "H6d+wvrsj5Bgh4Y2GeOFujYvXijMK1FG97bSDd7zaX8VY78X3a2Ey2Success.wpyo5ASiwWA8cW6gP1rejWjZMbPcS3k\u003d"
}
其中，sign为私钥priKey（L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8）对序列化后的其他请求参数（{"pubKey":"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a","time":"1635513688254","url":"https://www.sign.cash/api/apip1/v1/connect"}）所做的签名。
请求方保存API服务信息
请求方为其使用的每个APIP协议，分别保存以下信息：
| 信息名称 |
类型 |
说明 |
必填 |
| sid |
string |
接口服务的SID，即服务方在链上注册服务时的txid |
Y |
| pid |
string |
APIP协议的PID |
N |
| title |
string |
APIP协议的标题，如：APIP1V1_OpenAPI(zh-CN) |
N |
| sn |
int |
APIP协议编号 |
Y |
| ver |
int |
APIP协议版本号 |
Y |
| stdName |
string |
接口服务链上注册的英文标准名称 |
N |
| urlHead |
string |
connect的urlHead，相同sid的urlHead值相同 |
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 |
| sessionKey |
string |
当前生效的sessionKey，相同urlHead的各接口使用同一个sessionKey |
N |
| sessionName |
string |
sessionKey的双sha256哈希值的后6字节base64编码，请求时代表请求方 |
N |
| time |
time stamp |
当前生效的sessionKey获得的时间戳 |
N |
| days |
int |
当前生效的sessionKey的有效天数 |
N |
| apiBalance |
int64 |
请求方当前服务余额 |
all |
5. 响应
-
验证请求。服务方对请求依次验证：
-
1）验证用户。验证requester是否在用户列表中，用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000.
-
2）验证请求对象。验证签名内容中的“url”值是否与服务方当前接口的url相同，防止重放攻击。不同则返回1001
-
3）验证时间戳。验证当前时间戳减time的绝对值是否小于服务方设定的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.sessionKeyEncrypted |
string |
sessionKey的密文 |
0 |
| data.days |
int |
sessionKey的有效天数 |
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 |
设服务方验证请求无误后，为该请求方分配sessionKey为："d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"。
请求方公钥pubKey为："030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a"。
则响应参数为：
{
"code": "0",
"message": "Success.",
"data": {
"sessionKeyEncrypted": "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地址未保存，则视为新用户。 |
| sessionName |
string |
sessionKey的双sha256哈希值的后6字节base64编码，请求时代表请求方 |
| sessionKey |
string |
该用户当前的sessionKey |
| time |
int |
当前sessionKey发放时间，用于控制连接的有效期 |
| days |
int |
N |
数据请求接口
1. 接口名称
接口名称在相应APIP协议中定义。
示例：
在协议APIP99V1中定义接口 interface1
2. 请求方法
POST
3. URL
url = urlHead + urlTail
urlHead为 [服务方链上注册服务时的data.params.urlHead值],如："https://www.sign.cash/api/"
urlTail在具体的APIP协议的具体接口处定义，格式为：apip[协议编号]/v[协议版本号]/[接口名称]。如："apip99/v1/interface1"
示例:
urlHead = "https://www.sign.cash/api/"
urlTail = "apip99/v1/interface1"
url: "https://www.sign.cash/api/apip99/v1/interface1"
4. 请求参数
请求应包含以下通用参数：
| name |
type |
description |
requested |
| requester |
string |
请求方的sessionName |
Y |
| url |
string |
当前所请求api的url |
Y |
| time |
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协议规定。
将sessionKey加入除sign以外的其他请求参数并序列化后，做两次sha256计算，获得sign。
查询address包含“armX”，且1000<amount<=2000的条目，按amount升序排列，取前20条。
请求参数parameters：
{
"requester": "1111111111",
"time": 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(parametersWithoutSign.getBytes()))
=1111111111111111
5. 响应
-
验证请求：服务方按顺序验证请求
-
1）验证用户。验证requester是否在用户列表中，用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000。
-
2）验证请求对象。验证签名内容中的url值是否与服务方当前接口的url相同，防止重放攻击。不同则返回1001。
-
3）验证时间戳。验证当前时间戳减请求参数中time的绝对值是否小于服务方设定的windowTime，防止重放攻击。过期返回1002.
-
4）验证sessionKey时效。检查服务器保存的requeter的sessionKey是否过期。过期返回1004.
-
5）验证签名。在请求参数中加入requester的sessionKey做两次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 sessionKey has expired, please connect again. |
sessionKey过期，请重新连接 |
|
| 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 |
将sessionKey加入响应参数做两次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.","sessionKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))
= 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816
6. 请求方验证响应数据
请求方收到数据后，取出sign，加入sessionKey序列化后，做两次sha256哈希，与sign值相比较，一致则接受数据。以防止中间人攻击。
7. 请求方重置sessionKey
请求方在1）希望重置sessionKey，或2）收到错误码1004，sessionKey过期时，或3）收到错误码1000，并完成充值时，用connect接口申请新的sessionKey。
APIP简易查询语法
- 通用语法仅实现简单查询功能，复杂查询功能语法由API服务商自行定义和发布。
查询命令
1. all （全查询）
{
"all":{}
}
//查询所有条目。
2. ids （id查询）
{
"ids":["0000000000000","1111111111111"]
}查询id为"1111111111"或"22222222222"的条目
3. terms （精确查询）
{
"terms":{
"querys":["0000000000000","1111111111111"],
"fields":["pid","sid"]
}
} //查询字符串字段“address”值为"F000000000000"或"F111111111111"的条目。
{
"terms":{
"querys":["1000","2000"],
"fields":["cd","cdd"]
}
} //查询整数字段“fee”的值为"1000"或"2000"的条目。
4. part （部分查询）
- 对单一字段，搜索包含特定值的条目，可使用通配符*和?。
{
"part":{
"query":"arm?*“,
"fields":["addr","cid"]
}
} //查询“address”字段值以“‘arm’加一个任意字符”开头的条目。
5. match （模糊查询）
{
"match":{
"query":"good bad",
"fields":["article","post","reply"]
}
}
//在"article","post"和"reply"字段中，模糊查询包含’good‘或’bad‘（不区分大小写）的条目，并给出评分。
6. exist （非空查询）
{
"exist":"cid"
}
//查询“cid”字段存在且非null的条目。
7. nonexist （为空查询）
{
"nonexist":"cid"
}
//查询“cid”字段不存在或为null的条目
8. range （范围查询）
{
"range": {
"amount": {
"gt": 3000,
"lte": 10000
}
}
}//查询amount值大于3000，小于等于10000的条目。
{
"range": {
"cid": {
"gt": "c",
"lte": "f"
}
}
}//查询cid首字母为d、e和f的条目。
分页命令
1. size （请求数量）
{
"size":1000
}
//请求返回1000条。
2. sort （请求排序）
{
"sort":{
"address":"asc",
"cdd":"desc"
}
}
//第一级按"address"升序，第二级按cdd降序排列条目。
3. after （上次末位）
- 定位从某项之后开始获取。
- 必须与sort一起使用，并且与sort的字段名一一对应。
- 按照”sort“给出的顺序，从"after"值之后开始获取。
- 没有“after”则从排序第一项开始获取。
{
"after":["F000000000000",2000]
}
//按照address一级升序和cdd二级降序的排序，从address为F000000000000，cdd为2000之后的那一项开始获取size个条目。
其他规则
查询命令只能“与”组合
{
"part": {
"query":"*cash",
"fields":["addr"]
},
"range": {
"cid": {
"gt": "c",
"lte": "f"
}
},
"sort": {
"address": "asc",
"cdd": "desc"
},
"after": ["F000000000000", 2000],
"size": 1000
}
//查询"addr"字段以“cash”结尾，且cid首字母为d、e或f的条目，
//按"address"一级升序，"cdd"二级降序，从地址为"F000000000000",cdd为2000的条目之后开始，取1000条。
分页命令默认值
- size、sort、after可省略。
- sort的默认值由各数据相应协议给出。
- size默认为20条
- after默认为空,即从排序首位置开始获取。
