SpringBoot系列: 设计Restful风格的API

RESTful 架构
REST 并非一种技术或规范, 而是一种架构风格, 如果一个架构符合Rest的约束条件和原则, 就可以称作是 RESTful 架构.
REST全称是Representational State Transfer, 省略了定语 Resource, 完整的讲法是"资源表现性状态转移", 要设计符合RESTful风格的关键是, 应始终围绕资源来分析问题.

-------------------------
1. 使用 api 作为上下文
-------------------------
上下文path建议加上 api
http://192.168.1.1/api

或者使用api作为二级域名
http://api.xxxx.com

-------------------------
2. 增加一个版本标识
-------------------------
推荐在 url 增加版本标识, 也有做法是将版本加到 http 头上
http://192.168.1.1/api/v1.1

-------------------------
3. 确定 Http method
-------------------------
[安全]特性: 1次或多次操作都不会有副作用.
[幂等]: 多次操作的结果和1次操作的结果是一致的.

GET, [安全且幂等] 代表查询资源, 相当于数据库CRUD中的 Retrieve.
GET 动作应该是幂等操作, 也就是说多次 GET 操作, 结果应该是一致的, 理论上, 我们可以使用GET完成资源创建动作, 但这样违反了GET的幂等属性.
POST, [不安全且不幂等], 代替新增资源, 相当于数据库CRUD中的 Create.
PUT, [不安全但幂等], 代表更改资源, 客户端需要提供"完整"的资源属性. 相当于数据库CRUD中全字段的Update.
PATCH, [不安全但幂等], 代表更改资源, 客户端仅提供"需要更改"的资源属性. 相当于数据库CRUD中的 Update.
DELETE, [不安全但幂等], 代表删除资源, 因为要求幂等性, 所以这里的删除应该以逻辑删除方式实现. 相当于数据库CRUD中的 Update.

-------------------------
4. 返回结果
-------------------------
针对不同操作, 服务器向用户返回的结果应该符合以下规范.
GET /collection: 返回资源对象的列表(数组)
GET /collection/resource: 返回单个资源对象
POST /collection: 返回新生成的资源对象
PUT /collection/resource: 返回完整的资源对象
PATCH /collection/resource: 返回完整的资源对象
DELETE /collection/resource: 返回一个空文档

-------------------------
5. 状态码 和 错误处理
-------------------------
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

如果状态码是4xx, 就应该向用户返回出错信息. 一般来说, 返回的信息中将error作为键名, 出错信息作为键值即可.
{
error: "Invalid API key"
}

-------------------------
6. url 规范和示例
-------------------------
总则:
1. 尽量使用/来表示资源的层级关系, 比如 GET /zoos/ID/animals
2. 使用?追加控制参数, 而不是资源id
3. url中复合单词参数应该使用中划线或下划线, url尽量都是小写字母, 不推荐使用 lowerUpperCase 这样的写法.
4. url资源应该是名词, 操作应该由Http method指明, 而不是在url中使用 delete-user 或 create-user 字样.
5. url资源名词应该使用复数形式.

新增一个用户
POST http://192.168.1.1/api/v1.1/depts/1/users

查询用户, id为451
GET http://192.168.1.1/api/v1.1/depts/1/users/451

查询所有的用户
GET http://192.168.1.1/api/v1.1/depts/1/users

查询所有被禁的用户, 使用 ? 做过滤条件
GET http://192.168.1.1/api/v1.1/depts/1/users?disable=1

翻页查询, 增加 offset/limit 等控制参数
GET http://192.168.1.1/api/v1.1/depts/1/users?offset=1&limit=20&desc=created_at,id&asc=grade,updated_at

查询指定类型的用户
GET http://192.168.1.1/api/v1.1/depts/1/users?use-type=1

更新用户,id为451
PUT http://192.168.1.1/api/v1.1/depts/1/users/451

删除用户,id为451
DELETE http://192.168.1.1/api/v1.1/depts/1/users/451

查询两个用户, id为451和254
GET http://192.168.1.1/api/v1.1/depts/1/users/451,452
或
GET http://192.168.1.1/api/v1.1/depts/1/users/451;452

=============================
参考
=============================
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
http://www.cnblogs.com/ajianbeyourself/p/3751831.html