Bitshares 开发者系列(1)—— Api接口的访问方式steemCreated with Sketch.

in #bts-ws7 years ago (edited)

官方接口访问库 GitHub : https://github.com/bitshares/bitsharesjs-ws
在阅读源码之前,最好先浏览一遍 Bitshares 官方公开的开发文档,虽然文档中对开发细节描述的不是很清楚,但也能对系统的通讯方式有个详细的了解。

Graphene API 通讯方式


Bitshares 系统共支持两种 API 调用方式:

  • WebSocket Calls - 长连接调用
  • Remote Procedure Calls - HTTP 方式调用

官方 GitHub 仓库提供的 GUI 钱包客户端 bitshares-ui 就是使用 WebSocket 方式通讯的,此钱包客户端是使用 React 开发的前端工程,然后使用 Electron 工具打包成了各平台可用的桌面客户端,这样做的优势在于,技术栈全部使用前端技术,可以做功能的一次性开发,然后使用相关的打包工具,进行跨平台的客户端打包,能够同时进行 Web 端和 桌面客户端 的开发。

关于 Bitshares 官方的 GitHub 账号开源的几个项目,作一下简要的介绍,其中,bitshares-ui 项目依赖 bitsharesjs , 而 bitsharesjs 又依赖 bitsharesjs-ws 项目,它们之间的职责关系如下:

  • bitshares-ui 完整的钱包客户端项目,使用 React + Electron 技术栈,同时支持 Web 和 桌面客户端的打包。
  • bitsharesjs API业务工具,基层依赖 bitsharesjs-ws 项目进行API通讯,其模块内部封装并完成了大部分的业务API。
  • bitsharesjs-ws 针对 Graphene 系统定制的 WebSocket 接口访问通信工具,封装并定制了系统特有的API访问流程。

WebSocket 调用 API 数据结构


{
 "id"       : 1,            // 调用标识
 "method"   : "call",
 "params"   :               // 格式必须严格按照如下顺序传递
    [         
        0,                  //  API类型标识符
        "get_accounts",     //  接口名称
        [["1.2.0"]]         //  接口参数列表
    ]
}    

id 字段的作用是专门针对 WebSocket 方式的 API 定制的,我们知道 WebSocket 是长连接协议,像 Socket 编程一样,可以发送二进制和文本类型的数据。但是发送数据和返回数据之间是无序的,你可能发送的顺序是 A-api、B-api ,然而服务器端响应给你的顺序却可能是 B-result、A-result。
所以 API 在设计的时候特限定了一个 id 字段,当你发起 API 调用的时候指定一个唯一 id ,那么在响应结果里面,会把这个 id 再返回给你,你就可以根据这个 id 来区别响应结果应该怎么处理。

另外需要注意的就是 params 字段,此字段是一个数组类型,第一个元素代表 API 标识符,第二个元素代表要调用的 API 名称,第三个元素同样是一个数组类型,其数组中的每一个元素都将作为 API 的一个参数传递,并且应该注意参数的顺序与格式。

API 调用流程


Bitshares 系统的完整客户端节点提供了一系列可以通过 WebSocket 方式访问的API,但根据官方文档中描述的API调用流程,应该首先有一个初始化的调用过程:

  • 1.首先应该登录到完整节点 :
{"id":0, "method":"call", "params":[1, "login", ["",""]]}


  • 2.然后获取指定类型的API标识 :
// 你可以动态的修改 “database” 属性,来获取不同的 API 类型请求标识。
{"id":0, "method":"call", "params":[1, "database", []]}

// 此次请求调用返回结果里面的 "result" 值,就是 "database" 类型 API 的标识符。 
{"id":2, "result":2}


  • 3.你可以多次的进行第二步操作,拿到不同类型的 API 标识符,最后只需要之前介绍过的 API 数据结构指定好 idparams 参数格式,即可调用所有公开的 API 接口。

API 返回结果数据格式


调用成功 JSON 格式 :

{
  "id"      : 1,    //  调用 API 时传递的调用标识。
  "result"  : ...data...
}

调用失败 JSON 格式 :

{
  "id"    : 0,    // 调用 API 时传递的调用标识。
  "data"  : {
    "code"  : 1,
    "error" : {
      "code"    : error-code,
      "name"    : " .. name of exception .."
      "message" : " .. message of exception ..",
      "stack"   : [ .. stack trace .. ],
    },
  },
}

API 是否调用成功,可以简单的通过判断结果是否包含 resutl 字段来区分,假如包含 result 字段就可以认为调用成功,不同 API 有不同的 result 结构,届时根据 API 文档,分别进行解析处理即可。

Sort:  

Welcome to Steemit, I'm here to give you a vote on your very first post!

Thank you very much.

Congratulations @bts500, you have decided to take the next big step with your first post! The Steem Network Team wishes you a great time among this awesome community.


Thumbs up for Steem Network´s strategy

The proven road to boost your personal success in this amazing Steem Network

Do you already know that awesome content will get great profits by following these simple steps, that have been worked out by experts?