RESTful API最佳实践的一些理解
我的个人博客，RESTful API最佳实践的一些理解
什么是RESTful
简单的说：RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构。
先看REST是什么意思，英文Representational state transfer 表述性状态转移 其实就是对 资源 的表述性状态转移。
资源的地址 在web中就是URL （统一资源标识符）。
资源是REST系统的核心概念，所有的设计都是以资源为中心。
RESTful的基本概念：
1. 在REST中，一切的内容都被认为是一种资源
2. 每个资源都由URI唯一标识
3. 使用统一的接口处理资源请求（POST/GET/PUT/DELETE/HEAD）
4. 无状态
为什么要用 RESTful
RESTful 给我的最大感觉就是规范、易懂和优雅，一个结构清晰、易于理解的 API 完全可以省去许多无意义的沟通和文档。并且 RESTful 现在越来越流行，也有越来越多优秀的周边工具（例如文档工具 Swagger）。
域名
使用一个恰当的域名地址，比如：api.github.com，协议最好使用https。
版本
API 的版本号和客户端 APP 的版本号是毫无关系的，不要让 APP 将它们用于提交应用市场的版本号传递到服务器，而是提供类似于v1、v2之类的 API 版本号。版本号只允许枚举，不允许判断区间。
版本号拼接在 URL 中或是放在 Header 中都可以。例如：
api.xxx.com/v1/users
或：
api.xxx.com/users
version=v1
路径
推荐使用复数名词，最基础的 URL 就是以下几种：
-
GET /articles： 文章列表 -
GET /articles/id：文章详情 -
POST /articles/： 创建文章 -
PUT /articles/id：修改文章 -
DELETE /articles/id：删除文章
RESTful 中使用 GET、POST、PUT 和 DELETE 来表示资源的查询、创建、更改、删除，并且除了 POST 其他三种请求都具备幂等性（多次请求的效果相同）。需要注意的是 POST 和 PUT 最大的区别就是幂等性，所以 PUT 也可以用于创建操作，只要在创建前就可以确定资源的 id。
将 id 放在 URL 中而不是 Query Param 的其中一个好处是可以表示资源之间的层级关系，例如文章下面会有评论（Comment）和点赞（Like），这两项资源必然会属于一篇文章，所以它们的 URL 应该是这样的：
评论：
-
GET /articles/aid/comments： 某篇文章的评论列表 -
GET /comments/cid： 获取 -
POST /articles/aid/comments： 在某篇文章中创建评论 -
PUT /comments/cid： 修改评论 -
DELETE /comments/cid： 删除评论这里有一点比较特殊，永远去使用可以指向资源的的最短 URL 路径，也就是说既然
/comments/cid已经可以指向一条评论了，就不需要再用/articles/aid/comments/cid特意的指出所属文章了。点赞：
-
GET /articles/id/like：查看文章是否被点赞 -
PUT /articles/id/like：点赞文章 -
DELETE /articles/id/like：取消点赞
RESTful 中不建议出现动词，所以可以将这种关系作为资源来映射。并且由于大部分的关系查询都与当前的登录用户有关，所以也可以直接在关系所属的资源中返回关系状态。例如点赞状态就可以直接在获取文章详情时返回。注意这里我选择了 PUT 而不是 POST，因为我觉得点赞这种行为应该是幂等的，多次操作的结果应该相同。
Token 和 Sign
API 需要设计成无状态，所以客户端在每次请求时都需要提供有效的 Token 和 Sign，在我看来它们的用途分别是：
- Token 用于证明请求所属的用户，一般都是服务端在登录后随机生成一段字符串（UUID）和登录用户进行绑定，再将其返回给客户端。Token 的状态保持一般有两种方式实现：一种是在用户每次操作都会延长或重置 TOKEN 的生存时间（类似于缓存的机制），另一种是 Token 的生存时间固定不变，但是同时返回一个刷新用的 Token，当 Token 过期时可以将其刷新而不是重新登录。
- Sign 用于证明该次请求合理，所以一般客户端会把请求参数拼接后并加密作为 Sign 传给服务端，这样即使被抓包了，对方只修改参数而无法生成对应的 Sign 也会被服务端识破。当然也可以将时间戳、请求地址和 Token 也混入 Sign，这样 Sign 也拥有了所属人、时效性和目的地。
过滤信息
搜索：
/users/?query=xxx
过滤：
/users/?gender=1
对于某些特定且复杂的业务逻辑，不要试图让客户端用复杂的查询参数表示，而是在 URL 使用别名：：
/users/recommend
分页：
/users/?offset=10&limit=10
/articles/?cursor=2015-01-01 15:20:30&limit=10
/users/?page=2&pre_page=20
状态码
使用HTTP状态码+业务状态码，其中常用的HTTP状态码有：
-
200：请求成功
-
201：创建、修改成功
-
204：删除成功
-
400：参数错误
-
401：未登录
-
403：禁止访问
-
404：未找到
-
500：系统错误
仅仅使用 HTTP 状态码没有办法明确的表达错误信息，所以可以在里面再包一层自定义的返回码，例如：
成功时：
{ "code": 100, "msg": "成功", "data": {} }失败时：
{ "code": -1000, "msg": "用户名或密码错误" }data是真正需要返回的数据，并且只会在请求成功时才存在，msg只用在开发环境，并且只为了开发人员识别。客户端逻辑只允许识别code，并且不允许直接将msg的内容展示给用户。如果这个错误很复杂，无法使用一段话描述清楚，也可以在添加一个doc字段，包含指向该错误的文档的链接。
分页
分页布局一般分为两种，一种是在 Web 端比较常见的有底部分页栏的电梯式分页，另一种是在 APP 中比较常见的上拉加载更多的流式分页。这两种分页的 API 到底该如何设计呢？
1. 电梯式分页需要提供page（页数）和pre_page（每页的数量）
例如：
/users/?page=2&pre_page=20
而服务端则需要额外返回total_count（总记录数），以及可选的当前页数、每页的数量（这两个与客户端提交的相同）、总页数、是否有下一页、是否有上一页（这三个都可以通过总记录数计算出）。例如：
{
"pagination": {
"previous": 1,
"next": 3,
"current": 2,
"per_page": 20,
"total": 200,
"pages": 10
},
"data": {}
}
流式布局也完全可以使用这种方式，并且不需要查询总记录数（好处是减少一次数据库操作，坏处时客户端需要多请求一次才能判断是否到最后一页）。但是会出现数据重复和缺失的情况，所以更推荐使用游标分页。
2. 游标分页需要提供cursor(下一页的起点游标) 和limit(数量) 参数
例如：
/articles/?cursor=2015-01-01 15:20:30&limit=10
如果文章列表默认是以创建时间为倒序排列的，那么cursor就是当前列表最后一条的创建时间（第一页为当前时间）。
服务端需要返回的数据也很简单，只需要以此游标为起点的总记录数和下一个起点游标就可以了。例如：
{
"pagination": {
"next": "2015-01-01 12:20:30",
"limit": 10,
"total": 100,
},
"data": {}
}
如果total小于limit，就说明已经没有数据了。
流式布局的分页 API 还有一种情况很常见，就是下拉刷新的增量更新。它的业务逻辑正好和游标分页相反，但是参数基本一样：
/articles/?cursor=2015-01-01 15:20:30&limit=20
返回数据有两种可能，一种是增量更新的数据小于指定的数量，就直接将全部数据返回（这个数量可以设置的相对大一些），客户端会将这些增量更新的数据添加在已有列表的顶部。但是如果增量更新的数据要大于指定的数量，就会只返回最新的 n 条数据作为第一页，这时候客户端需要清空之前的列表。例如：
{
"pagination": {
"limit": 20,
"total": 100,
},
"data": {}
}
如果total大于limit，说明增量的数据太多所以只返回了第一页，需要清空旧的列表。
