井通区块链Api订阅服务介绍

本节介绍井通区块链标准接口的订阅服务功能。

1、订阅功能简介

为了减少前端软件的复杂度，井通区块链标准接口(REST API)提供了井通钱包地址的websocket长连接服务。前端软件可以通过 websocket连接向标准接口订阅和井通地址相关的交易信息。一旦订阅成功，任何和该地址相关的交易信息将会通过相应的 websocket连接传给订阅客户端。
REST API订阅后台服务器的测试环境是:wss://tapi.jingtum.com:5443/v2。
由于订阅功能是采用websocket实现的，因此要测试订阅功能，可以采用websocket在线测试工具。 这里推荐一款比较好用的websocket在线测试工具:http://ws.douqq.com/ 。 另外，由于websocket返回的都是JSON格式的数据，比较难以阅读，可以采用JSON在线解析工具。 这里推荐一款好用的JSON在线解析工具:https://www.bejson.com/ 。

2、连接订阅服务器

例子:
1)在浏览器里面打开 http://ws.douqq.com/ 网站。
2)在ws链接输入框里面输入 wss://tapi.jingtum.com:5443/v2 ，点击后面的“连接”按钮。 3)如果不出意外，就会连接上订阅服务器。如下如所示:

连接成功，返回如下信息:

{
"success": true,
"type": "connection",
"id": "d5172daa-a2b2-46ad-bb90-750ccb0a8023"
}

如果写程序调用，连接订阅服务器后，就可以实现自动化处理订阅请求的返回消息。

3、发起订阅请求

1)客户端连接上订阅服务器后，就可以向服务器发起订阅请求。订阅请求格式如下:

{
"command": "subscribe",
"type": "account",
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM"
}

订阅请求中，必须将订阅用户的钱包地址和订阅类型一起提交上来。 参数type表示订阅类型，包含3种: account:订阅某个账号的交易记录、 transactions:订阅所有交易记录、
ledger:订阅账本消息
订阅成功之后，返回:

{
"success": true,
"command": "subscribe",
"type": "account",
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM"
}

一旦订阅成功，这个订阅状态就会一直持续，直到客户端取消订阅，或者关闭订阅。如果由于网络原因，导致订阅失效，也 需要重新订阅。
当请求的JSON格式不对时，返回:

{
"success": false, "error": "xxx"
}

当请求的参数有问题时，返回:

{
"account": "jDUjqoDZLhzx4DCf6pvSivjkjgtRESY62c", "success": false,
"all": true,
"command": "subscribe",
"type": "account",
"error": "XXX"
}

error包括缺少account，type，account格式不对，type格式不对等，分别是: 1.missing account 2.account is not valid jingtum address
3.invalid type，……

4、接收消息

客户端订阅了钱包的交易消息，然后向该钱包发送支付交易，客户端可以收到如下的交易信息:

{
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM", "success": true,
"type": "Payment",
"transaction": {
"date": 1522238560,
"hash": "608A45B90BDC30DA0DADAF3EC590C06819AB73A20D2D4D6C581261117C32B44A", "type": "received",
"fee": "0.01",
"result": "tesSUCCESS",
"memos": ["", "U"],
"counterparty": "jpLpucnjfX7ksggzc9Qw6hMSm1ATKJe3AF",
"amount": {
"value": "1.55", "currency": "SWT", "issuer": ""
},
"effects": [] }
}

基本格式为:
account: 帐号，订阅的井通钱包地址。
type: 交易类型，与API里面的信息一致，主要有Payment、OfferCreate、OfferCancel和RelationSet transaction: 交易信息，与API里面的信息一致。
在用户被动成交时，用户也会收到交易相关的信息。
当交易失败时，会有如下的格式的消息:

{
"account": "jsGn5UAxwTuYfN5aa6TBC2KZyDDoFJfM8b", "type": "Payment",
"success": false,
"transaction": {
"result": "tecNO_DST_INSUF_SWT",
"message": "xxx" }
} 

通过success可以判断返回的交易结果是成功的还是失败的，其他的失败记录均即时反馈回给用户，无需在订阅中获得。

5、取消订阅 客户端在连接上服务之后，通过发送取消订阅请求进行取消订阅，取消订阅请求如下:

{
"command": "unsubscribe",
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM", "type": "account"
}

取消订阅成功时候，返回:

{
"success": true,
"command": "unsubscribe",
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM", "type": "account"
}

当请求的JSON格式有问题时，返回:

{
"success": false, "error": "xxx"
}

当请求的参数不正确时，返回:

{
"account": "jQNdYXxgNHY49oxDL8mrjr7J6k7tdNy1kM", "success": false,
"command": "unsubscribe",
"type": "account",
"error": "XXX"
}

取消订阅，参数不正确主要是account缺失或者格式不正确: a)account is missing b)Invalid type 等

6、关闭订阅 通过发送如下命令，关闭订阅

{
"command": "close"
}
关闭订阅之后，后台返回订阅关闭结果
{
"command": "close", "success": true
}

作为一个开发者，有一个学习的氛围跟一个交流的圈子特别重要，下面是我们的社区交流群，不管你是小白还是大牛欢迎入住，分享经验、讨论技术、社区开发。大家一起交流学习共同成长！希望开发者少走弯路。
1.社区开发者大赛 QQ 群：568285439
2.社区论坛：http://bbswtc.com
3.社区公众号：SWTC 互动社区、SWTC 社区
4.github：https://github.com/swtcpro