设计API

[TOC] ## 创建模型URI ``` /devices /devices/{id} /configurations /configurations/{id} /devices/{id}/configurations /devices/{id}/configurations/{id} ``` ## 合理设计参数 ``` 比如设计一个最近登陆的所有用户 https://example.com/api/users?recently_login_day=3 ``` ``` 搜索用户，并按照注册时间降序 https://example.com/api/users?recently_login_day=3 ``` ``` 搜索用户，并按照注册时间升序、活跃度降序 https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc ``` ``` 分页 https://api.cnblogs.com/api/blogposts/picked?pageIndex=pageIndex&pageSize=pageSize ``` ## 统一返回数据格式 code * 包含一个整数类型的HTTP响应状态码 status * 包含文本：`success`，`fail`或`error`。 * HTTP状态响应码在500-599之间为`fail`， * 在400-499之间为`error`， * 其它均为`success`（例如：响应状态码为1XX、2XX和3XX） message * 当状态值为`fail`和`error`时有效，用于显示错误信息 data * 包含响应的body。当状态值为`fail`或`error`时，data仅包含错误原因或异常名称、或者null也是可以的 * 返回成功的响应json格式 ``` { "code": 200, "message": "success", "data": { "userName": "123456", "age": 16, "address": "beijing" } } ``` * 返回失败的响应json格式 ``` { "code": 401, "message": "error message", "data": null } ``` ## http状态码 1** 请求未成功 2** 请求成功、表示成功处理了请求的状态代码。 3** 请求被重定向、表示要完成请求，需要进一步操作。 通常，这些状态代码用来重定向。 4** 请求错误这些状态代码表示请求可能出错，妨碍了服务器的处理。 5**（服务器错误）这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误，而不是请求出错。