RESTful

RESTful作为一种软件架构风格、设计风格,在Web应用上非常流行。基于这个风格设计的软件可以更简洁,REST 接口可以直接在浏览器上测试,给开发和测试过程带来很多便利。WeEvent的所有功能都支持RESTful协议访问。

协议说明

  • HTTP方法可以使用GETPOST,并且统一使用UTF8字符集。

  • 输入参数为Query String格式,注意使用UrlEncode

  • 应答的HTTP状态码是 200,输出参数统一是json格式,Content-type: application/json

  • 调用异常时,返回异常信息BrokerException

  1. {"code": 200202, "the transaction does not correctly executed."}

代码样例

  1. public class Rest {
  2. public static void main(String[] args) {
  3. System.out.println("This is WeEvent restful sample.");
  4. try {
  5. SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
  6. RestTemplate rest = new RestTemplate(requestFactory);
  7. // ensure topic exist "com.weevent.test"
  8. Boolean result = rest.getForEntity("http://localhost:8080/weevent/rest/open?topic={}&groupId={}",
  9. Boolean.class,
  10. "com.weevent.test",
  11. "1").getBody();
  12. System.out.println(result);
  13. // publish event to topic "com.weevent.test"
  14. SendResult sendResult = rest.getForEntity("http://localhost:8080/weevent/rest/publish?topic={}&groupId={}&content={}",
  15. SendResult.class,
  16. "com.weevent.test",
  17. "1",
  18. "hello weevent".getBytes(StandardCharsets.UTF_8)).getBody();
  19. System.out.println(sendResult.getStatus());
  20. System.out.println(sendResult.getEventId());
  21. } catch (RestClientException e) {
  22. e.printStackTrace();
  23. }
  24. }
  25. }

完整的代码,请参见RESTful代码样例

接口说明

RESTful接口包括两大类功能:一类是主题TopicCRUD管理,包括opencloseexiststatelist;一类是事件的发布和订阅,包括publishsubscribeunsubscribe

创建Topic

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/open?topic=com.weevent.test&groupId=1
  • 应答
  1. true
  • 说明

  • topic:主题。ascii值在[32,128]之间。支持通配符按层次订阅,因’+’、’#’为通配符的关键字故不能为topic的一部分,详情参见MQTT通配符

  • groupId: 群组Idfisco-bcos 2.0+版本支持多群组功能。2.0以下版本不支持该功能,可以不传,其他接口类似。

重复open返回true

关闭Topic

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/close?topic=com.weevent.test&groupId=1
  • 应答
  1. true

检查Topic是否存在

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/exist?topic=com.weevent.test&groupId=1
  • 应答
  1. true

发布事件

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/publish?topic=com.weevent.test&groupId=1&content=123456&weevent-format=json
  • 应答
  1. {
  2. "topic": "com.weevent.test",
  3. "eventId": "2cf24dba-59-1124",
  4. "status": "SUCCESS"
  5. }
  • 说明

    • content :用户自定义数据。需要特别注意content需进行UrlEncode编码,GET方法支持的QueryString最大长度为1024字节。
    • weevent-json:可选参数。用户自定义拓展,以weevent-开头。
    • status:SUCCESS,说明是发布成功,eventId是对应的事件ID。

订阅事件

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/subscribe?topic=com.weevent.test&groupId=1&subscriptionId=c8a600c0-61a7-4077-90f6-3aa39fc9cdd5&url=http%3a%2f%2flocalhost%3a8080%2fweevent%2fmock%2frest%2fonEvent
  • 应答
  1. c8a600c0-61a7-4077-90f6-3aa39fc9cdd5
  • 说明

    • topic:主题。ascii值在[32,128]之间。支持通配符按层次订阅,因’+’、’#’为通配符的关键字故不能为topic的一部分,详情参见MQTT通配符
    • url:事件通知回调CGI,当有生产者发布事件时,所有的事件都会通知到这个url
    • subscriptionId:第一次订阅可以不填。继续上一次订阅subscriptionId为上次订阅ID。

取消订阅

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/unSubscribe?subscriptionId=c8a600c0-61a7-4077-90f6-3aa39fc9cdd5
  • 应答
  1. true
  • 说明

    • subscriptionId:Subscribe成功订阅后,返回的订阅ID。

获取Event详情

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/getEvent?eventId=2cf24dba-59-1124&groupId=1
  • 应答
  1. {
  2. "topic": "hello",
  3. "content": "MTIzNDU2",
  4. "extensions":{"weevent-format":"json"},
  5. "eventId": "2cf24dba-59-1124"
  6. }
  • 说明

    • eventId:事件ID
    • content:事件内容,MTIzNDU2123456Base64之后的值。
    • extensions:用户自定义拓展数据。注意

以下管理端接口,业务程序里一般用不到,可以直接安装Goverance模块来使用这部分功能。

当前Topic列表

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/list?pageIndex=1&pageSize=10&groupId=1
  • 应答
  1. {
  2. "total": 50,
  3. "pageIndex": 1,
  4. "pageSize": 10,
  5. "topicInfoList": [
  6. {
  7. "topicName": "123456",
  8. "topicAddress": "0x420f853b49838bd3e9466c85a4cc3428c960dde2",
  9. "senderAddress": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3",
  10. "createdTimestamp": 1548211117753
  11. }
  12. ]
  13. }
  • 说明

    • total:Topic的总数量。
    • pageIndex:表示查询第几页,从0开始 。
    • pageSize:分页大小(0,100),超出这默认每页10个数据。
    • topicInfoList:Topic 详细信息列表。

查询某个Topic详情

  • 请求
  1. $ curl http://localhost:8080/weevent/rest/state?topic=com.weevent.test&groupId=1
  • 应答
  1. {
  2. "topicName": "com.weevent.test",
  3. "topicAddress": "0x171befab4c1c7e0d33b5c3bd932ce0112d4caecd",
  4. "senderAddress": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3",
  5. "createdTimestamp": 1548328570965,
  6. "sequenceNumber": 9,
  7. "blockNumber": 2475
  8. }
  • 说明

    • topicName : 事件名称
    • topicAddress : Topic 区块链上的合约地址
    • createdTimestamp :Topic 创建的时间
    • sequenceNumber:已发布事件数。
    • blockNumber:最新已发布事件的区块高度。

获取订阅列表

  • 请求
  1. $ curl http://localhost:8080/weevent/admin/listSubscription
  • 应答
  1. {
  2. "127.0.0.1:8080": {
  3. "a78d05b7-7e44-4f85-b1d7-395362768af0": {
  4. "interfaceType": "restful",
  5. "notifyingEventCount": "0",
  6. "notifyTimeStamp": "2019-04-09 20:33:15",
  7. "subscribeId": "a78d05b7-7e44-4f85-b1d7-395362768af0",
  8. "topicName": "com.webank.test",
  9. "notifiedEventCount": "0"
  10. },
  11. "3da9691d-ec72-4e8d-b17a-679d8a9ea111": {
  12. "interfaceType": "stomp",
  13. "notifyingEventCount": "0",
  14. "notifyTimeStamp": "2019-04-09 20:33:15",
  15. "subscribeId": "3da9691d-ec72-4e8d-b17a-679d8a9ea111",
  16. "topicName": "com.webank.test",
  17. "notifiedEventCount": "0"
  18. }
  19. }
  20. }
  • 说明

    • interfaceType:监听请求类型 RESTfulJsonRPCMQTTSTOMP
    • notifyingEventCount:待通知事件的数量。
    • notifiedEventCount:已通知事件数量
    • notifyTimeStamp:最近通知事件时间戳。
    • subscribeId:订阅ID
    • topicName :事件主题。