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&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 | 其它错误 | |