Restful API设计规范（参考）

Restful API 特点

Resource ： 一切面向资源，Url中的资源使用名词复数，原则上不使用动词；

    例如：资源是：cars、fences
    http://api.xyz.com/v1/cars
    http://api.xyz.com/v1/fences

Collection ：资源的集合，使用资源的复数形式；
Version ： 所有的API必须制定版本号，新的版本建议对之前版本API做兼容性处理；

    http://api.xyz.com/v1/cars
    http://api.xyz.com/v2/cars

HTTP Verb ：使用Http动词来实现资源的增删改查；

    GET：用于获取资源，返回资源对象实体或集合；
    POST：用于新增资源，返回新增的资源实体；
    PUT：用于修改资源，返回修改后的资源实体；
    DELETE：用于删除资源，返回空；

HTTP Status ：使用Http状态码作为业务状态码；

    200：请求资源成功，返回请求的数据对象或列表；
    201：创建/修改资源成功，返回操作完成的数据对象，如有敏感数据，在业务层脱敏；
    204：删除资源成功，返回空；
    400：请求失败（参数错误或服务端捕获的错误）；
    401：未授权（需要重新登录）；
    403：没有权限访问资源；
    404：请求的资源不存在；
    500：服务器内部错误；

JSON ：使用JSON传输数据，包括接口返回，新增、修改传输数据；

---

接口请求参数

注意：所有接口的请求参数中，全部使用小写字母，如果属性有多个单词组成，使用下划线连接

1.如果是请求某个具体的资源，该参数将作为请求url的一部分，例如：

    GET         http://api.xyz.com/v1/cars/58
    DELETE      http://api.xyz.com/v1/users/10556054

2.如果进行添加、修改操作，需要传输结构化的数据，则使用Json Object：

    POST            http://api.xyz.com/v1/cars
    data: {
        "username": "admin01",
        "password": "123456",
        "organization_id": 192
    }

    PUT         http://api.xyz.com/v1/cars
    data: {
        "id": 12,
        "username": "admin01",
        "password": "123456",
        "organization_id": 192
    }

3.如果是分页、排序等表示过滤的意义参数，使用字符串拼接url的方式：

    GET         http://api.xyz.com/v1/cars?page=1&page_size=10

---

接口返回模板

注意：所有接口的返回数据的参数中，全部使用小写字母，如果属性有多个单词组成，使用下划线连接

在Restful API中，可以直接使用Http状态码来表示业务执行的结果，考虑到执行成功时，msg字段并没有什么实际意义。所以Restful API接口可以直接返回data中的数据。
例如：请求 http://api/xyz.com/v1/cars/58 ，返回

Http Status: 200
Response Body：
    {
        "id": 58,
        "name": "audi",
        "color": "write
    }

或者没有请求到的时候

Http Status: 404
Response Body：车辆不存在

如果请求的是列表，同样需要返回列表本身，列表总数，页面等相关数据。例如请求 http://api/xyz.com/v1/cars?page=1&page_size=10

Http Status: 200
Response Body：
    {
        "list": [
            {},{},{}
        ],
        "total": 141,
        "page":1,
        "page_size":10
    }

参数说明及规约：关于分页获取列表数据，统一使用参数命名和格式

字段名称	字段类型	说明
list	array	查询到的数据列表
total	int	该查询条件下的总记录数量
page	int	当前所在页
page_size	int	每页显示记录数