147 lines
4.7 KiB
Markdown
Executable File
147 lines
4.7 KiB
Markdown
Executable File
API概述
|
||
=======
|
||
|
||
目录
|
||
----
|
||
|
||
- [请求格式](#请求格式)
|
||
- [GET](#GET)
|
||
- [POST](#POST)
|
||
- [对象输出参数](#对象输出参数)
|
||
- [分页参数](#分页参数)
|
||
- [嵌套参数](#嵌套参数)
|
||
- [简化参数](#简化参数)
|
||
- [排序参数](#排序参数)
|
||
- [响应格式](#响应格式)
|
||
- [返回单个对象](#返回单个对象)
|
||
- [返回多个对象](#返回多个对象)
|
||
- [返回失败](#返回失败)
|
||
- [错误码定义](#错误码定义)
|
||
|
||
|
||
# 请求格式
|
||
|
||
## GET
|
||
|
||
GET请求时参数必须放在URL中，如：
|
||
|
||
> GET /api/posturedata/?device=466970701492096 HTTP/1.1
|
||
> Host: 203.195.166.239:8888
|
||
> Accept: */*
|
||
|
||
## POST
|
||
|
||
POST命令参数可放在URL，也可放在BODY中
|
||
|
||
> POST /api/account/login HTTP/1.1
|
||
> Host: 203.195.166.239:8888
|
||
> Accept: */*
|
||
> Content-Length: 29
|
||
> Content-Type: application/x-www-form-urlencoded
|
||
> para1=value1¶2=value2
|
||
|
||
# 对象输出参数
|
||
|
||
## 分页参数
|
||
|
||
当返回对象列表时，可以对列表进行分页
|
||
|
||
| 名称 | 必须 | 类型 | 说明 |
|
||
| ------------ | ---- | ------------ | ------------------------------ |
|
||
| page | 否 | int | 页数1~N，缺省1 |
|
||
| rows_per_page| 否 | int | 每页行数，缺省20 |
|
||
|
||
## 嵌套参数
|
||
|
||
返回对象中有引用类型（Reference）的属性时，可以将被引用的对象嵌套到返回中。
|
||
|
||
- 原属性输出为ObjectID方式
|
||
- 新增一个以$开头的属性，形如"$[attr_name]", 其中attr_name为原属性名，其内容是完整的json对象。
|
||
|
||
| 名称 | 必须 | 类型 | 说明 |
|
||
| ------------ | ---- | ------------ | ------------------------------ |
|
||
| depth | 否 | int | 嵌套层数(1-4)，缺省2 |
|
||
|
||
## 简化参数
|
||
|
||
输出简化后的对象，只包含特定的属性。必须在定义对象时指出简化对象包含哪些属性，如未指定，则输出对象的前10个属性。
|
||
|
||
| 名称 | 必须 | 类型 | 说明 |
|
||
| ------------ | ---- | ------------ | ------------------------------ |
|
||
| small | 否 | int | 1-完整，0-简化。缺省为1 |
|
||
|
||
|
||
## 排序参数
|
||
|
||
当返回对象列表时，可以对列表进行排序。指定按哪几个属性进行排序。
|
||
|
||
|
||
| 名称 | 必须 | 类型 | 说明 |
|
||
| ------------ | ---- | ------------ | ------------------------------ |
|
||
| order_by | 否 | string | 需要排序的属性名, 逆序用'-', 多个属性用','连接。如：'order_by=email,-username'表示先按email字典序，然后按username逆序 |
|
||
|
||
|
||
# 响应格式
|
||
|
||
返回内容统一是json格式。
|
||
|
||
## 返回单个对象
|
||
|
||
当返回单个对象时，返回格式。 范例：
|
||
|
||
{
|
||
"success": true, // 成功标志
|
||
"obj_name": "obj name", // 对象名
|
||
"obj": {"key1":"val1", "key2":"val2", ...} // 返回的对象内容
|
||
}
|
||
|
||
## 返回多个对象
|
||
|
||
当返回多个对象时，返回格式。范例：
|
||
|
||
{
|
||
"success": true, // 成功标志
|
||
"obj_name": "obj name", // 对象名
|
||
"objs": [{obj1}, {obj2}, ...] // 对象列表
|
||
"page": { // 分页信息
|
||
"rows_per_page": intval // 每页行数
|
||
"total": intval, // 总数
|
||
"page_count": intval, // 分页数
|
||
"page_current": intval, // 当前页号
|
||
}
|
||
}
|
||
|
||
|
||
## 返回失败
|
||
|
||
失败时返回错误码和出错信息。 范例：
|
||
|
||
{
|
||
"success": false, // 成功标志
|
||
"error_code": 1, // 错误码
|
||
"error_desc": "error description", // 错误描述
|
||
"error_url": "/api/account/login", // 错误URL
|
||
}
|
||
|
||
# 错误码定义
|
||
|
||
| 返回码 | 错误信息 | 说明 |
|
||
| ------------ | -------- | ------------------------------ |
|
||
| 0 | 成功 | |
|
||
| 1 | 错误 | |
|
||
| 101 | 未授权 | 需登录 |
|
||
| 102 | 没有操作权限 | 没有相应的操作权限，不需重新登录 |
|
||
| 103 | 用户不存在 | |
|
||
| 104 | 用户已存在 | |
|
||
| 105 | 登录验证失败 | |
|
||
| 106 | 设备不在线 | |
|
||
| 201 | 缺少必填参数 | |
|
||
| 202 | 参数格式错误 | |
|
||
| 203 | 对象不存在 | |
|
||
| 204 | 参数取值错误 | |
|
||
| 301 | 数据库错误 | |
|
||
| 302 | 数据唯一性错误 | |
|
||
| 401 | 数据同步失败 | |
|
||
| 999 | 其它错误 | |
|
||
|