API 使用指南

API 使用指南

概述

云平台提供了统一的 API 接口给前端页面，应用程序以及第三方平台使用。

云平台提供的 API 接口主要使用 REST 风格和 JSON 数据格式。

版本

V2.0

作者

@author ChengZhen

修改历史

2019/4/1

REST API

大部分 API 只用到 HTTP GET 和 POST 方法, 当使用 GET 方法时，请求参数放在 URL 参数中；而当使用 POST 方法时，请求参数必须放在请求消息体内，内容格式为 application/x-www-form-urlencoded 或者 application/json.

URL 地址

REST API URL 访问地址为:

http(s)://{domain-name}/v2/:service/:entity/:action

RESTful URL 规则

大部分实体都会实现创建、更新、删除、查询 4 个操作, 所以统一 URL 格式如下:

:METHOD http(s)://{domain-name}/v2/:service/:entity/:entityId/

例如:

REST URL 规则

为了方便管理, API 的 URL 和前端视图页面的 URL 必须分开.
采用 url 路径前缀区分:

大部分实体都会实现创建、更新、删除、查询 4 个操作, 所以统一 URL 格式如下:

http(s)://{domain-name}/:version/:service/:entity/:action/

例如:

请求参数

数据类型

TYPE DATA TYPES DESCRIPTION
Number int, float, double 数值
String string 字符串 (UTF-8)
Boolean boolean 布尔型
Array array 数组
Byte[] byte[] base64 编码的二进制字符数组
Date date string 日期字符串

应答结果

大部分 API 都会返回 JSON 格式的应答结果

必须包含 Content-Type 等相关的 HTTP Header, 如:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100

{
    ...
}

状态码

不管是否成功或失败，一般 API 的 HTTP 应答码总是为 200, 除非发生其他网络层等系统错误, 如 404 找不到资源, 具体请查看 HTTP 相关 RFC 文档.

返回错误结果

API 返回的 JSON 对象中会包含 API 执行的结果的状态码和消息, 具体请参考"API 错误代码"一章

例如:

{
    "code": 205001,
    "error": "Need you follow uid."
}

返回成功的结果

返回结果总是以键值对的形式返回

返回单个对象或其他信息

总是返回一个表示结果的 JSON 对象, 可以包含子对象

// 返回单个设备对象
{
    "name": "xxx",
    "size": 100
}

返回分页查询结果

总是返回一个表示结果的 JSON 对象的数组以及相关的元数据

// 返回一个设备列表
{
    "devices": [{ // 结果列表
      // ...
    }],
    "total": 100, // 记录总数等元数据
    "offset": 0,
    "limit": 20
}

列表查询

PARAMETER TYPE DEFAULT DESCRIPTION
offset Number 0 表示返回的结果集开始位置需要跳过的记录数
limit Number 30 返回最大结果数, 最大值为 100
orderBy String '_id' 排序的字段名
order String 'asc' 排序方式, 可选择升序或降序
select String - 选择要返回的字段，没有指定时返回所有字段
populate String - 展开关联的实体
q String - 查询过滤规则
query String - 查询字符串

分页参数

分页示例如下:

假如有一个集合总共有 134 条记录, 查询时每页显示 20 条记录.

第一页:

page = 1;
limit = pageSize = 20;
offset = (page - 1) * limit = (1 - 1) * 20 = 20;

`GET /list?offset=0&limit=20

{
    "total": 134,
    "offset": 0,
    "limit": 20,
    "items": [{
        "index": 0,
        "name": "item1"
    }...]
}

显示结果:

第二页:

GET /list?offset=20&limit=20

{
    "total": 134,
    "offset": 20,
    "limit": 20,
    "items": [{
        "index": 20,
        "name": "item21"
    }...]
}

显示结果:

排序参数

order 这个值对大小写不敏感

VALUE NOTE
asc 升序
desc 降序

比如:

GET /list?orderBy=created&order=desc

表示返回结果按创建时间降序排列.

字段选择

通过 select 参数选择要返回的字段的名称，多个字段名称用空格 (+号)分隔

例如:

select=id+name+title

表示只返回 id, name 和 title 字段，其他字段将不会出现在返回结果中

展开选项

通过 populate 参数选择要展开的关联实体的名称

关键词查询

query 参数表示搜索关键词

过滤规则

q 参数表示该规则, 操作采用逗号(,) 分割

目前平台这个参数主要用于模糊查询

规则类型

符号: 等于(==), 不等于(!=)

符号: 大于(>), 小于(<), 不小于(>=), 不大于(<=)

符号: 像(~=)

解析结果

返回 MongoDB 的查询格式的 JS 对象, 比如解析下述的过滤规则字符串:

tid==008098022c9b,at>1508717995100,at<1508724704042,hid~=A01122330003

解析结果如下:

{
    "tid": {
        "$eq": "008098022c9b"
    },
    "at": {
        "$gt": "1508717995100",
        "$lt": "1508724704042"
    },
    "hid": {
        "$regex": "A01122330003"
    }
}

响应结果

示例:

GET /device/list?limit=20&offset=40&order=asc&orderBy=name&q=at>1508717995100

响应内容:

{
    "devices": [{
        "id": "1234567890",
        "name": "test"
    }],
    "total": 134,
    "offset": 40,
    "limit": 20
}

错误码

因为 HTTP 状态码数量有限, 为了表示更具体的错误类型, 云平台采用了自定义的错误状态码

返回值格式

云平台的应答消息 HTTP 状态码一般都为 200 OK, 然后通过返回 JSON 内容来描述具体的错误消息, 它的格式如下:

{
    "code": 205001,
    "error": "Missing necessary parameters",
    "message": "parameter uid"
}

错误码说明

结构

错误码由 6 位数组成, 例如: 205001, 它的组成内容如下:

20 5001
2 4
Error Level 具体错误代码

错误级别代码

2 位数, 用来表示错误级别

VALUE 说明
10 ~ 19 系统级错误,所有服务模块通用
20 ~ 99 服务级错误,服务器自定义错误

系统级错误代码

表示系统级别的或所有服务通用的错误类型

CODE ERROR NOTE
100500 Internal server error 系统内部错误
100503 Service unavailable 服务不可用
105001 Database access error 数据库访问错误
100403 Permission denied 该资源需要更高的授权
104001 Miss required parameter 缺失必需的参数
104002 Parameter error 错误的参数
100404 Object does not exists 访问的对象不存在
104041 Object already exists 要创建的对象已存在
104042 Delete method not allowed 不允许删除
100401 Unauthorized 未授权的访问
100400 Bad request 错误的请求
100405 Method not allow 不允许的方法
100408 Request timeout 请求超时
100409 Conflict 冲突
104009 Duplicate name 重名错误

错误信息示例

很多错误通过 message 属性来描述更细节的错误信息, 以便更好的提示用户或者测试, 常见的描述方式有:

缺失必选参数

在 message 中描述所有缺失的参数的名称

{
    "code": 104001,
    "error": "Miss required parameter",
    "message": {
        "paramters": "id,name,title,content"
    }
}

请求长度超过限制

在 message 中描述具体错误

{
    "code": 100400,
    "error": "Bad request",
    "message": "The length of the request body must less than 2MB"
}

参数值非法

在 message 中描述非法的参数的名称以及具体错误

{
    "code": 104002,
    "error": "Parameter error",
    "message": {
        "paramters": [{
            "name": "name",
            "error": "The length of the value must less than 32."
        }]
    }
}

对象不存在

{
    "code": 100022,
    "error": "Object does not exists",
    "message": {
        "id": "123456789012345678901234",
        "entity": "User"
    }
}

对象已存在

在 message 中描述已存在的对象的信息

{
    "code": 100023,
    "error": "Object already exists",
    "message": {
        "id": "123456789012345678901234",
        "name": "test",
        "entity": "User"
    }
}

不允许删除

在 message 中描述不能删除的具体原因

{
    "code": 100024,
    "error": "Delete not allowed",
    "message": {
        "id": "123456789012345678901234",
        "cause": "Can't delete the system administrator",
        "entity": "User"
    }
}