接口规范

QLEN平台接口提供RESTful风格的WebAPI来实现对外服务，为了描述清楚这些接口，下面将从接口地址、HTTP方法、请求参数、响应结果这几个方面来详细说明。

1. 接口地址

接口地址，所有QLEN接口地址的前缀统一都是QLEN平台的接口网址(生产环境：https://api.qlen.cn/v1，沙箱环境：https://demoapi.qlen.cn/v1)，后面跟接口URI，接口URI将在各个接口中具体说明。

HTTP方法，QLEN接口利用HTTP协议的GET、POST、PUT、DELETE方法来区分对资源的操作类型，如下表：

请求参数，除了名称和类型外，还要描述两个方面：一是是否为必需项，如果不是必需项，则在传参时可以根据需要省略，服务端会使用默认值代替；另一个就是参数传入方式，说明如下：

传参方式	说明
query	参数以查询字符串的形式跟在URI后面，如：/token?seq=123
path	参数作为URI的一部分，如：/node/seq/123
json	参数以JSON格式封装成结构体，然后在请求中以Content-Type: application/json类型提交
file	参数是上传文件，文件以Content-Type: multipart/form-data类型提交

响应结果，包括HTTP协议中的状态码和响应结构体，下面详细描述。

QLEN接口主要利用了以下一些HTTP状态码：

响应结构体是服务端执行完用户请求后返回的结果，QLEN接口返回的响应结构体统一以JSON格式封装，响应结构体各属性描述如下：

属性	类型	作用
status	布尔型	指示请求是否成功
code	整型	请求失败时的错误编码
message	字符串	请求失败时的错误类型
data	复合型	请求成功时返回的是结果数据，失败时返回的是错误提示信息

{  
    "status":true,  
    "code":0,  
    "message":"OK",  
    "data":"d7e4045f8ddf4ed7beeb2db402fb4686"  
}

{  
    "status":false,  
    "code":211,  
    "message":"PARAM_INVALID",  
    "data":"引用哈希必须为64位十六进制字符"  
}

请求成功时，HTTP状态码固定为200。响应结构体中status, code, message的值也都是固定的，分别为

"status":true
"code":0
"message":"OK"

而data则随请求的不同有不同的结构，下面对几种复杂结构加以说明：

属性	类型	作用
vendorId	字符串	服务编码
count	整型	该服务编码创建的节点总数

请求失败时，HTTP状态码为除200以外的其他编码，具体视错误类型来决定。响应结构体中status固定为false，data为附加错误消息，而code和message的值则随错误的不同而不同，具体如下表所示：