关于RESTful API的一些思考与疑问

最近在研究API规范的最佳实践。发现关于RESTful API规范的信息甚是模糊，没有一个明确的权威的说法，至少国内搜到的信息是这样的。比如下面的三篇文章，其中的内容差异很大，甚至相反（比如PUT和POST的用法），有此可见整个RESTful API规范实现的乱象。

RESTful API 规范 v1.0

Restful API 的设计规范

REST API URI的七大设计原则

其实RESTful API并没有一个权威的标准（至少笔者没有查到），REST只是一个抽象概念，RESTful API相当于其具体应用实现，既然没有绝对的标准，那么今天就来讨论一下吧。

1、是否启用PUT、DELETE？修改和创建，哪个用PUT哪个用POST？

参考：POST增、GET查、DELETE删、PUT改

eg：GET /companies、GET /companies/3、POST /companies/3、DELETE /companies/3、PUT /companies/3

讨论：HTTP 1.1 这个版本是当前版本，包含GET(0.9) HEAD(1.0) POST(1.0) OPTIONS PUT DELETE TRACE CONNECT这8个方法，兼容性是毫无问题的。但是POST和PUT的区别是什么？

2、是否可以有动词？名词单数还是复数？

参考：不应该有动词（用POST、GET、DELETE、PUT区分），全是名词复数。

eg：/companies/3/employees/45

讨论：这样看起来的确优雅，但是下面的场景如何处理呢。

• 详情页与编辑页（浏览器地址）如何设计？例：员工列表->员工详情 / 员工编辑
• 详情页就是子层级的列表页时如何设计？例：公司列表->公司详情（就是部门列表）->部门详情（就是员工列表）->员工详情
• tabs怎么办？用query？

3、单词连接用"-"横线、"_"下划线，还是驼峰？

参考：用横线"-"，防止整个地址有超链接下划线时"_"看不出，RFC 3986将URI定义为区分大小写，但scheme 和 host components除外。

eg：/salary-records/3/paybill-details/34

讨论：python的变量推荐用"_"，这种习惯会被带到这里；另外，返回的数据里的key是否应该采用驼峰？eslint的报错很烦的。

4、结尾应不应该包含斜杠“/”？

参考：不加

讨论：在地址栏与API中，以"/"为结尾有何区别？

5、地址栏的URL与API的get请求如何区分？

参考：用域名区分

eg：https://www.example.com/companies/3 、 https://apis.example.com/companies/3

讨论：会不会混淆或有其他副作用？另外还有2当中讨论的第一个场景。

6、是否与http统一状态码？

参考：返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为200，然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。由于rest api是直接使用的HTTP协议，所以它的状态码也要尽量使用HTTP协议的状态码。

eg：200 OK 服务器返回用户请求的数据，该操作是幂等的

201 CREATED 新建或者修改数据成功

204 NOT CONTENT 删除数据成功

400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的

401 Unauthoried 表示用户没有认证，无法进行操作

403 Forbidden 用户访问是被禁止的

422 Unprocesable Entity 当创建一个对象时，发生一个验证错误

500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功

503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等

讨论：现在的success=true，个人觉得信息量不足。

7、版本控制放在URL中还是HEADER中？

讨论：现在的payroll是放在URL中

8、非标准RESTful API真的不好吗？

/companies/3/departments/15/employees/45

VS

/employee?company=3&depart=15&employee=45

请参考另一篇文章，并留下宝贵意见params与query分别适合于何种场景？

参考文献：

RESTful API Designing guidelines — The best practices

RESTful Web Services Cookbook中文版（这书好烂）

理解RESTful架构——阮一峰

RESTful API 设计指南——阮一峰