最近主导了公司的一次RESTful API的重新设计以及代码重构，查阅了很多不同公司的做法，整理了一套相对完整的设计指导，在这里分享给大家。文章主要分为两部分，第一部分会介绍RESTful基本的设计指南，第二部分则会详细介绍具体设计中碰到的问题。
RESTful没有「准则」
REST的全称——Representational state transfer，表现层状态转移是一种Web服务的设计思想，核心在于RESTful把Web实体抽象为资源，而对资源的种种操作，则都通过HTTP协议的动词来表现。
「一切皆为资源」，可是如何去把一个实体转化为资源，不同的API设计者会有不同的想法。RESTful并不是一种很强的约束，也不是一套万能的框架，具体如何设计，还是要根据实际的业务需求、安全性、易用性等方面去考虑。
URL基本构成
域名
如图所示，URL的第一部分是域名加上“/api/”或直接将API融入域名中，来表明这是一个用于API的专属链接。
模块名
紧接着是一个模块名，表示该API所在的具体的业务模块，像谷歌就有youtube, drive等等。但如果你的API只对应单一的业务，这一部分是可以省略的。
Spotify的API只对音乐提供不同的接口，就省略了这一部分。
版本号
基本上大多数的API提供方都会把版本号放在URL内，通常发布后的REST服务不会在同一个版本内做大的改动。
资源名
资源名的设计需要遵循一定的原则，这些原则会让你的API看起来更加清晰、统一以及易用，但这并不是强制性的规范。
- 使用名词
动词都将被转移至HTTP动词，资源名词和HTTP动词的结合能更清晰地表现出API的操作 - 使用复数
不管这个资源是不是一个列表或组合，都用复数来表现，可以减轻设计者的头疼，也可以避免冗余的相近的API - 使用英文小写
- 避免使用下划线“_”，用横线“-”代替
参数
当需要对URL返回的资源进行过滤或者筛选时，就需要用到参数。
常见的URL参数分两种，一种是直接写在URL内的，也被成为URL变量，如下图的1：
https://www.sampleapis.com/drive/v2/files/1
另一种是加在URL的最后，通常作为查询参数：
https://www.sampleapis.com/drive/v2/files?id=1
HTTP动词
HTTP动词可以表明对资源的增删改查操作，它们的具体含义如下：
| 动词 | 具体操作 | 返回消息体 |
|---|---|---|
| GET | 获取资源 | 返回资源对象 |
| POST | 新增资源 | 返回新增的资源对象或资源的位置 |
| PUT | 完整地替换资源 | 返回修改后的资源对象或资源的位置 |
| PATCH | 更新资源的部分信息 | 返回修改后的资源对象或资源的位置 |
| DELETE | 删除资源 | 无需返回消息体 |
HTTP状态码
HTTP状态码作为HTTP请求的返回的一部分，已经能涵盖非常多的状态信息，这边只列举了一些常用的状态码：
| 状态码 | 具体信息 |
|---|---|
| 200 OK | 服务器返回成功，通常会附带消息体 |
| 201 Created | 新建或修改服务器的成功 |
| 202 Accepted | 请求已被接服务器接收并开始处理，用于异步处理 |
| 400 Bad Request | 请求有错误，服务器未处理（4开头的错误码通常都是客户端发出的请求有问题） |
| 404 Not Found | 未找到请求的资源 |
| 409 Confilct | 通常是对已经存在的资源进行了重复创建，服务器认为是冲突 |
| 500 Internal Server Error | 服务器发生错误（5开头的错误码通常是服务器端发生异常） |
认证
RESTful API一般建议使用OAuth2.0的框架做身份认证，配合以JWT作为Token的格式。OAuth2.0保证了RESTful API的无状态性。
REST API 设计技巧
其实在这次重构中，因为碰到了许多不同的应用场景，也分享一下一些设计API时的技巧。
URL变量还是参数？
上面有提到，取一个id为1的资源时，可以使用URL变量（resources/1）或是URL参数(resources?id=1)的方式。但是如果要取得id从1到5的资源，URL变量就会变得很奇怪了，这时候使用URL参数就更加合适。URL参数也可以用来做分页、排序等功能。
非增删改查的操作
HTTP动词能够表示对资源的增删改查操作，可是如果是其他的操作呢？比如播放、喜欢歌曲，启动、关闭系统...这时候HTTP动词好像就无能为力了。传统的API设计方法如下：
/songs/1/play
/songs/1/like
可这样不是违反了URL中不能出现动词的规则了吗？但这确实是一种解决方法，而且许多大公司也这样做，这样的API其实足够清晰易用，没什么理由能够让人拒绝。
如果一定要遵守不出现动词的规则，下面有一个方法，也可以试一下：
/songs/1?operation=play
/songs?id=1,2,3,4,5&operation=like
这个方法的还有一个好处在于，它可以同时对多个资源进行操作。无论选择哪种形式，记得在你的API里保持一致性。
文档
RESTful API绝对需要良好的文档说明，文档不仅可以帮助API使用者了解具体的数据格式以及资源请求方式，也可以帮助API开发者在版本演技和维护时，不断审视需求等。
RESTful文档通常需要包含具体的URL资源以及对应的各种HTTP动词的操作解释、请求和返回的格式、示例请求等，比较成熟的文档框架可以参考Swagger https://swagger.io/。
