RESTful¶

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

协议说明¶

HTTP方法可以使用GET和POST，并且统一使用UTF8字符集。
输入参数为Query String格式，注意使用UrlEncode。
应答的HTTP状态码是 200，输出参数统一是json格式，Content-type: application/json。

调用异常时，返回异常信息BrokerException。

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

代码样例¶

public class Rest {
    public static void main(String[] args) {
        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={}",
                    Boolean.class,
                    "com.weevent.test").getBody();
            System.out.println(result);

            // publish event to topic "com.weevent.test"
            SendResult sendResult = rest.getForEntity("http://localhost:8080/weevent/rest/publish?topic={}&content={}",
                    SendResult.class,
                    "com.weevent.test",
                    "hello weevent".getBytes(StandardCharsets.UTF_8)).getBody();

            System.out.println(sendResult.getStatus());
            System.out.println(sendResult.getEventId());
        } catch (RestClientException e) {
            e.printStackTrace();
        }
    }
}

上述代码样例，演示了使用RESTful如何创建主题和发布事件。程序执行效果和在浏览器上直接访问http://localhost:8080/weevent/rest/open?topic=com.weevent.test 和http://localhost:8080/weevent/rest/publish?topic=com.weevent.test&content=hello weevent是一样的。

完整的代码，请参见RESTful代码样例。

接口说明¶

RESTful接口包括两大类功能：一类是主题Topic的CRUD管理，包括open、close、exist、state、list；一类是事件的发布和订阅，包括publish、subscribe、unsubscribe 。

创建Topic¶

请求

$ curl http://localhost:8080/weevent/rest/open?topic=com.weevent.test

应答
```
true
```
说明 topic: Topic名字，ascii值在[32,128]之间的都为有效字符，最大长度32字节。重复open返回true 。

关闭Topic¶

请求

$ curl http://localhost:8080/weevent/rest/close?topic=com.weevent.test

应答
```
true
```

检查Topic是否存在¶

请求

$ curl http://localhost:8080/weevent/rest/exist?topic=com.weevent.test

应答
```
true
```

发布事件¶

请求

$ curl http://localhost:8080/weevent/rest/publish?topic=com.weevent.test&content=123456

应答

{
    "topic": "com.weevent.test",
    "eventId": "2cf24dba-59-1124",
    "status": "SUCCESS"
}

说明

content ：123456 ，需要特别注意两点：1、content的UrlEncode编码；2、GET方法支持的QueryString最大长度为1024字节。

status：SUCCESS，说明是发布成功，eventId是对应的事件ID。

订阅事件¶

请求

$ curl http://localhost:8080/weevent/rest/subscribe?topic=com.weevent.test&subscriptionId=c8a600c0-61a7-4077-90f6-3aa39fc9cdd5&url=http%3a%2f%2flocalhost%3a8080%2fweevent%2fonsubscribe

应答
```
c8a600c0-61a7-4077-90f6-3aa39fc9cdd5
```
说明
- topic：主题名称。
- url：事件通知回调CGI，当有生产者发布事件时，所有的事件都会通知到这个url。
- subscriptionId：第一次订阅使用空字符串””。继续上一次订阅，subscriptionId是上次订阅ID。
- 返回值是订阅IDc8a600c0-61a7-4077-90f6-3aa39fc9cdd5。

取消订阅¶

请求

$ curl http://localhost:8080/weevent/rest/unSubscribe?subscriptionId=c8a600c0-61a7-4077-90f6-3aa39fc9cdd5

应答
```
 true
```
说明
- 如果Broker没有配置zookeeper模块，该接口无法使用。no broker.zookeeper.ip configuration, can't support CGI subscription 。
- subscriptionId：Subscribe成功订阅后，返回的订阅ID。

获取Event详情¶

请求

$ curl http://localhost:8080/weevent/rest/getEvent?eventId=2cf24dba-59-1124

应答

{
    "topic": "hello",
    "content": "MTIzNDU2",
    "eventId": "2cf24dba-59-1124"
}

说明
- eventId：事件ID
- content：事件内容，MTIzNDU2是123456的Base64之后的值。

注意

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

当前Topic列表¶

请求

$ curl http://localhost:8080/weevent/rest/list?pageIndex=1&pageSize=10

应答

{
    "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 详细信息列表。

查询某个Topic详情¶

请求

$ curl http://localhost:8080/weevent/rest/state?topic=com.weevent.test

应答

{
    "topicName": "com.weevent.test",
    "topicAddress": "0x171befab4c1c7e0d33b5c3bd932ce0112d4caecd",
    "senderAddress": "0x64fa644d2a694681bd6addd6c5e36cccd8dcdde3",
    "createdTimestamp": 1548328570965
}

说明
- topicName ：事件名称
- topicAddress ： Topic 区块链上的合约地址
- createdTimestamp ：Topic 创建的时间

区块链节点信息¶

请求

$ curl http://localhost:8080/weevent/admin/blockchaininfo

应答

{
    "blockNumber": 17056,
    "nodeIdList": [
       "7c79f9fb09366f1b872d8c6fffa888754e61e5dcddb8ed8e49a4b294c6d652111a65dfa4163910abe9d08f842e5cb700e3d981f51dd07e460caa29699033b82f"
    ],
    "nodeIpList": [
        "[10.107.105.239:30306]",
        "[10.107.105.239:30305]",
        "[10.107.105.239:30304]"
    ]
}

获取订阅列表¶

请求

$ curl http://localhost:8080/weevent/admin/listSubscription

应答

{
 "127.0.0.1:8080": {
        "a78d05b7-7e44-4f85-b1d7-395362768af0": {
            "interfaceType": "restful",
            "notifyingEventCount": "0",
            "notifyTimeStamp": "2019-04-09 20:33:15",
            "subscribeId": "a78d05b7-7e44-4f85-b1d7-395362768af0",
            "topicName": "com.webank.test",
            "notifiedEventCount": "0"
        },
        "3da9691d-ec72-4e8d-b17a-679d8a9ea111": {
            "interfaceType": "stomp",
            "notifyingEventCount": "0",
            "notifyTimeStamp": "2019-04-09 20:33:15",
            "subscribeId": "3da9691d-ec72-4e8d-b17a-679d8a9ea111",
            "topicName": "com.webank.test",
            "notifiedEventCount": "0"
        }
    }
}

说明
- interfaceType：监听请求类型 RESTful、JsonRPC、MQTT 、STOMP。
- notifyingEventCount：待通知事件的数量。
- notifiedEventCount：已通知事件数量
- notifyTimeStamp：最近通知事件时间戳。
- subscribeId：订阅ID
- topicName ：事件主题。