RESTful¶
RESTful
作为一种软件架构风格、设计风格,在Web应用上非常流行。基于这个风格设计的软件可以更简洁,REST
接口可以直接在浏览器上测试,给开发和测试过程带来很多便利。
RESTful
都是对STOMP
协议的一个补充,支持WeEvent
主题的CRUD
管理等功能以及事件发布。
协议说明¶
HTTP
方法可以使用GET
和POST
,并且统一使用UTF8
字符集。输入参数为
Query String
格式,注意使用UrlEncode
。应答的
HTTP
状态码是200
,输出参数统一是json
格式,Content-type: application/json
。调用异常时,返回异常信息
BrokerException
。{"code": 200202, "message":"the transaction does not correctly executed."}
代码样例¶
public class Rest {
public static void main(String[] args) {
System.out.println("This is WeEvent restful sample.");
try {
SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
RestTemplate rest = new RestTemplate(requestFactory);
// ensure topic exist "com.weevent.test"
Boolean result = rest.getForEntity("http://localhost:8080/weevent/rest/open?topic={topic}&groupId={groupId}",
Boolean.class,
"com.weevent.test",
WeEvent.DEFAULT_GROUP_ID).getBody();
System.out.println(result);
// publish event to topic "com.weevent.test"
SendResult sendResult = rest.getForEntity("http://localhost:8080/weevent/rest/publish?topic={topic}&groupId={groupId}&content={content}",
SendResult.class,
"com.weevent.test",
WeEvent.DEFAULT_GROUP_ID,
"hello WeEvent".getBytes(StandardCharsets.UTF_8)).getBody();
System.out.println(sendResult);
} catch (RestClientException e) {
e.printStackTrace();
}
}
}
完整的代码,请参见RESTful代码样例 。
接口说明¶
RESTful
接口包括两大类功能:一类是主题Topic
的CRUD
管理,包括open
、close
、exist
、state
、list
;一类是事件发布publish
。
创建Topic¶
请求
$ curl "http://localhost:8080/weevent/rest/open?topic=com.weevent.test&groupId=1"
应答
true
说明
topic:主题。
ascii
值在[32,128]
之间。支持通配符按层次订阅,因’+’、’#’为通配符的关键字故不能为topic的一部分,详情参见MQTT通配符 。groupId: 群组
Id
,fisco-bcos 2.0+
版本支持多群组功能。2.0以下版本不支持该功能,可以不传,其他接口类似。重复
open
返回true
。
关闭Topic¶
请求
$ curl "http://localhost:8080/weevent/rest/close?topic=com.weevent.test&groupId=1"
应答
true
检查Topic是否存在¶
请求
$ curl "http://localhost:8080/weevent/rest/exist?topic=com.weevent.test&groupId=1"
应答
true
发布事件¶
请求
$ curl "http://localhost:8080/weevent/rest/publish?topic=com.weevent.test&groupId=1&content=123456&weevent-format=json"
应答
{ "topic": "com.weevent.test", "eventId": "2cf24dba-59-1124", "status": "SUCCESS" }
说明
- content :用户自定义数据。需要特别注意
content
需进行UrlEncode
编码,GET
方法支持的QueryString
最大长度为1024字节。 - weevent-json:可选参数。用户自定义拓展,以
weevent-
开头。 - status:
SUCCESS
,说明是发布成功,eventId
是对应的事件ID。
- content :用户自定义数据。需要特别注意
获取Event详情¶
请求
$ curl "http://localhost:8080/weevent/rest/getEvent?eventId=2cf24dba-59-1124&groupId=1"
应答
{ "topic": "hello", "content": "MTIzNDU2", "extensions":{"weevent-format":"json"}, "eventId": "2cf24dba-59-1124" }
说明
- eventId:事件ID
- content:事件内容,
MTIzNDU2
是123456
的Base64
之后的值。 - extensions:用户自定义拓展数据。
注意
以下管理端接口,业务程序里一般用不到,可以直接安装Goverance
模块来使用这部分功能。
当前Topic列表¶
请求
$ curl "http://localhost:8080/weevent/rest/list?pageIndex=1&pageSize=10&groupId=1"
应答
{ "total": 50, "pageIndex": 1, "pageSize": 10, "topicInfoList": [ { "topicName": "123456", "topicAddress": "0x420f853b49838bd3e9466c85a4cc3428c960dde2", "senderAddress": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3", "createdTimestamp": 1548211117753 } ] }
说明
- total:
Topic
的总数量。 - pageIndex:表示查询第几页,从0开始 。
- pageSize:分页大小(0,100),超出这默认每页10个数据。
- topicInfoList:
Topic
详细信息列表。
- total:
查询某个Topic详情¶
请求
$ curl "http://localhost:8080/weevent/rest/state?topic=com.weevent.test&groupId=1"
应答
{ "topicName": "com.weevent.test", "topicAddress": "0x171befab4c1c7e0d33b5c3bd932ce0112d4caecd", "senderAddress": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3", "createdTimestamp": 1548328570965, "sequenceNumber": 9, "blockNumber": 2475 }
说明
- topicName : 事件名称
- topicAddress :
Topic
区块链上的合约地址 - createdTimestamp :
Topic
创建的时间 - sequenceNumber:已发布事件数。
- blockNumber:最新已发布事件的区块高度。
获取群组列表¶
请求
$ curl "http://localhost:8080/weevent/admin/listGroup"
应答
{ "data":[ "1","2" ], "code":0, "message":"success" }
获取 节点ip数组¶
请求
$ curl "http://localhost:8080/weevent/admin/listNodes"
应答
{ "data": [ "127.0.0.1:7000" ], "code": 0, "message": "success" }
说明
- data:节点ip数组。
获取订阅列表¶
请求
$ curl "http://localhost:8080/weevent/admin/listSubscription?nodeIp=127.0.0.1:7000"
应答
{ "data": { "127.0.0.1:7000": { "5d39d5c1-3aea-48aa-93b2-416624155d0f": { "interfaceType": "stomp", "notifiedEventCount": "1712", "notifyingEventCount": "0", "notifyTimeStamp": "2019-11-06 11:28:30", "topicName": "com.weevent.rest", "subscribeId": "5d39d5c1-3aea-48aa-93b2-416624155d0f", "remoteIp": "127.0.0.1", "createTimeStamp": "2019-11-05 21:21:57", "groupId": "1" } } }, "code": 0, "message": "success" }
说明
- interfaceType:监听请求类型
RESTful
、JsonRPC
、MQTT
、STOMP
。 - notifyingEventCount:待通知事件的数量。
- notifiedEventCount:已通知事件数量
- notifyTimeStamp:最近通知事件时间戳。
- subscribeId:订阅ID
- topicName :事件主题。
- interfaceType:监听请求类型
获取版本信息¶
请求
$ curl "http://localhost:8080/weevent/admin/getVersion"
应答
{ "code":"0", "message":"success", "data": { "weEventVersion": "1.1.0", "gitCommitTimeStamp": "2019-09-16 18:01:23", "gitBranch": "master", "gitCommitHash": "a5b022b" } }
说明
- weEventVersion:
WeEvent
版本号。 - gitCommitTimeStamp:
WeEvent
最近一次提交git的时间。 - gitBranch:
WeEvent
构建分支。 - gitCommitHash:
WeEvent
最近一次提交git的CommitHash。
- weEventVersion:
获取节点个数、区块数量、交易数量¶
请求
$ curl "http://localhost:8080/weevent/admin/group/general?groupId=1"
应答
{ "code":"0", "message":"success", "data": { "nodeCount": "4", "latestBlock": "100", "transactionCount": "5260" } }
说明
- nodeCount:节点个数。
- latestBlock:区块数量。
- transactionCount:交易数量。
获取区块链交易列表¶
请求
$ curl "http://localhost:8080/weevent/admin/transaction/transList?groupId=1&pageNumber=1&pageSize=10"
应答
{ "code":"0", "message":"success", "data": { "total":1, "pageIndex":1, "pageSize":10, "pageData":[{ "blockNumber": 5364, "blockTimestamp": "2019-10-15 14:48:01", "createTime": null, "modifyTime": null, "transFrom": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3", "transHash": "0xb3585cf385a595e5af425d360693e6759d8db5c1a98ebb46277b38c014ec8626", "transTo": "0xa40c864c28ee8b07dc2eeab4711e3161fc87e1e2" }] } }
说明
- total:当前区块交易总条数。
- pageIndex:页码。
- pageSize:页面展示条数。
- blockNumber:区块高度。
- blockTimestamp:区块交易时间。
- createTime:创建时间。
- modifyTime:修改时间。
- transFrom: 发送者的地址。
- transHash:交易哈希。
- transTo:接收者的地址。
获取交易哈希列表¶
请求
$ curl "http://localhost:8080/weevent/admin/block/blockList?groupId=1&pageNumber=1&pageSize=10"
应答
{ "code":"0", "message":"success", "data": { "total":1, "pageIndex":1, "pageSize":10, "pageData":[{ "blockNumber": 5364, "blockTimestamp": "2019-10-15 14:48:01", "createTime": null, "modifyTime": null, "pkHash": "0x382d17374619233978c2f5c8dfc88fea1bb70af52ea824c8ec99982d66b455cd", "sealer": "0x3", "sealerIndex": 1, "transCount": 1 }] } }
说明
- total: 区块总数。
- pageIndex:页码。
- pageSize:页面展示条数。
- blockNumber:区块高度。
- blockTimestamp:区块交易时间。
- createTime:创建时间。
- modifyTime:修改时间。
- pkHash:区块哈希。
- sealer:共识节点序号。
- sealerIndex:节点序号为index的nodeId。
- transCount:交易次数。
获取节点列表¶
请求
$ curl "http://localhost:8080/weevent/admin/node/nodeList?groupId=1&pageNumber=1&pageSize=10"
应答
{ "code":"0", "message":"success", "data": { "total":1, "pageIndex":1, "pageSize":10, "pageData":[{ "nodeId": "543095f2a4a7ec910c4d62fcde2754871c559d375fba9a11aab94cb7c7ae8eef8f55250558a7412d14f11faeb7d31c55cec36746ce5644c749a4674888fe46eb", "nodeName": null, "pbftView": 23, "nodeType":"sealer", "blockNumber": 5364, "createTime": null, "modifyTime": null, "nodeActive": 1 }] } }
说明
- total: 节点总数。
- pageIndex:页码。
- pageSize:页面展示条数。
- nodeId:节点id。
- nodeName:节点名称。
- pbftView:PBFT视图。
- nodeType:节点类型。
- blockNumber:区块高度。
- nodeActive:节点运行状态。
- createTime:创建时间。
- modifyTime:修改时间。
获取节点ip数组¶
请求
$ curl http://localhost:8080/weevent/admin/listNodes
应答
{ "data": [ "127.0.0.1:7000" ], "code": 0, "message": "success" }
说明
- data:节点ip数组。