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)
目录
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位，应转换为13位。
密码算法
哈希算法
无特殊说明，哈希算法采用两次sha256算法，即:sha256(sha256(byte[] message_bytes))，哈希值为Hex，字母为小写.
加密算法
无特殊说明，文本和文件加解密采用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的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”]
"prot": [string array, 所遵循的协议]
"urlHead": [string, API的url的首部]
"pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
"params":{
"urlHead": [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路径的共同部分（urlHead）。
- 请求方 链下订购API服务
请求方按照订购方式，向服务方订购API服务。服务方记录请求方的身份（FCH地址）和充值余额，开始服务。
- 请求方 发出连接服务请求
请求方通过connect接口，向服务方发起包含自身pubKey的连接请求和私钥签名，以获得后续数据请求使用的对称密钥symKey，详情参见[##connect接口](##connect接口）。
- 服务方 验证请求分配密钥
服务方对请求进行安全验证后，发放用请求方pubKey加密的对称密钥symKey。具有相同urlHead的接口共用同一个symKey。
- 请求方 解密保存symKey
请求方用自己的私钥priKey解密密文，获得symKey，保存用于后续数据请求。
1-7步骤的流程图：
- 请求方 发出数据服务请求
请求方根据自身数据需求，选择服务方的对应接口，构造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在请求方同意购买，并填写或选择支付金额后，为请求方构造包含
购买标记的交易，由请求方确认后发送交易。 -
- 请求方自行构造包含
购买标记的交易完成支付。
- 请求方自行构造包含
-
-
请求方的
购买标记，即购买交易的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 = 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 |
| timestamp | time stamp | 精确到毫秒的时间戳，防止重放攻击 | Y |
| sign | string | 用请求方私钥priKey对序列化后的其他参数的签名，防止身份伪造 | Y |
- 签名
请求方用自己的私钥priKey对除sign之外的请求参数序列化后，进行签名，得到sign，加入请求json。
- 示例
请求参数
{
"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 |
| 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 |
| symKey | string | 当前生效的symKey，相同urlHead的各接口使用同一个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 = 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 | 请求方的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条。
请求参数parameters：
{
"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(parametersWithoutSign.getBytes()))
=1111111111111111
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简易查询语法
- 通用语法仅实现简单查询功能，复杂查询功能语法由API服务商自行定义和发布。
查询命令
1. all （全查询）
- 获取全部条目。
{
"all":{}
}
//查询所有条目。
2. ids （id查询）
- 获取给定id条目，可同时查询多个值。
{
"ids":["1111111111","22222222222"]
}查询id为"1111111111"或"22222222222"的条目
3. terms （精确查询）
- 对单一字段精确匹配，可同时查询多个值。
{
"terms":{
"address":["F000000000000","F111111111111"];
}
} //查询字符串字段“address”值为"F000000000000"或"F111111111111"的条目。
{
"terms":{
"fee":["1000","2000"];
}
} //查询整数字段“fee”的值为"1000"或"2000"的条目。
4. part （部分查询）
- 对单一字段，搜索包含特定值的条目，可使用通配符*和?。
{
"part":{
"address":"arm?*“
}
} //查询“address”字段值以“‘arm’加一个任意字符”开头的条目。
5. matchs （模糊查询）
- 对多个字段，分词模糊查询给定内容。
{
"matchs":{
"query":"good bad",
"fileds":["article","post","reply"]
}
}
//在"article","post"和"reply"字段中，模糊查询包含’good‘或’bad‘（不区分大小写）的条目，并给出评分。
6. exist （非空查询）
- 查询某个字段存在且非null的条目。
{
"exist":"cid"
}
//查询“cid”字段存在且非null的条目。
7. nonexist （为空查询）
- 查询某个字段不存在或为null的条目
{
"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": {
"address": "*cash"
},
"range": {
"cid": {
"gt": "c",
"lte": "f"
}
},
"sort": {
"address": "asc",
"cdd": "desc"
},
"after": ["F000000000000", 2000],
"size": 1000
}
//查询"address"字段以“cash”结尾，且cid首字母为d、e或f的条目，
//按"address"一级升序，"cdd"二级降序，从地址为"F000000000000",cdd为2000的条目之后开始，取1000条。
分页命令默认值
- size、sort、after可省略。
- sort的默认值由各数据相应协议给出。
- size默认为20条
- after默认为空,即从排序首位置开始获取。