API概述

目录

• 请求格式
  • GET
  • 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&para2=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	其它错误