RESTful API设计规范
⼀、什么是RESTful？
⼜称REST（Representational State Transfer），⼀种软件架构⻛格、设计风格，而不是标准，只是提供了⼀组设计原则和约束条件。它主要⽤于客户端和服务器交互类的软件。
其核心是⾯向资源，REST专门针对网络应⽤设计和开发方式，以降低开发的复杂性，提⾼系统的可伸缩性。
在RESTful架构中，每个网址代表⼀种资源（resource），所以网址中不能有动词，只能有名词。
⼀般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使⽤复数，除非没有合适的复数形式，如：weather。
二、设计概念和准则
- 网络上的所有事物都可以被抽象为资源(resource)；
- 每个资源都有唯⼀的资源标识(resource identifier)，对资源的操作不会改变这些标识；
- 所有的操作都是无状态的；
- 分层系统，表示组件⽆法了解它与之交互的中间层以外的组件。通过将系统知识限制在单个层，可以限制整个系统的复杂性，促进了底层的独⽴性。
三、为什么要使用RESTful API？
- 面向资源（URI），具有解释性；
- 行为（GET / POST / PUT / PATCH / DELETE）与资源（URI）分离，更加轻量；
- 数据描述简单，使⽤JSON、XML、PROTOBUFFER即可全覆盖，主要使⽤JSON；
四、协议
API与⽤户的通信协议，⼀般使⽤HTTP协议，更安全情况下使⽤HTTPS。
五、域名
应该尽量将API部署在专⽤域名之下：
如果确定API很简单，不会有进⼀步扩展，可以考虑放在主域名下：
六、版本
在每个API对应的URL中，应有⼀个版本号，以便将来服务升级后，所有版本的客户端可以正常使用，如下：
https://api.example.com/v1/topics/
https://api.example.com/v2/topics/
https://api.example.com/v3/topics/
七、http请求⽅式
八、路由（路径）
• 每个⽹址中不能有动词，只能有名词。并且应该使⽤复数，除⾮没有合适的复数形式，如：weather。
https://api.example.com/v1/topics/ —> 所有帖⼦
• 对于个体或个类名下资源，可以直接在路径上添加具体的id来表现，如下：
https://api.example.com/v1/topics/100001/info // id为100001的帖⼦的详情
https://api.example.com/v1/users/12345/topics/ // id为12345的⽤户名下所有帖⼦
• 更多例子[带请求方法]
[GET] https://api.example.com/v1/topics/ — 获取所有帖⼦(列表)
[POST] https://api.example.com/v1/topics/ — 新建帖⼦
[PUT] https://api.example.com/v1/topics/100001 — 更新完整帖⼦
[PATCH] https://api.example.com/v1/topics/100001 — 更新帖⼦部分信息
[DELETE] https://api.example.com/v1/topics/100001 — 删除帖⼦
[GET] https://api.example.com/v1/groups/1/topics/ — 获取某组所有帖⼦(列表)
[GET] https://api.example.com/v1/users/12345/profile — 获取某⽤户资料
[PUT] https://api.example.com/v1/users/12345/profile — 更新某⽤户资料
[GET] https://api.example.com/v1/users/12345/labels — 获取某⽤户所有标签
九、过滤信息（url中?后⾯的参数）
使用过滤信息的原因：
- 单⼀的 url 路径不能表现出所有的场景的，起到了补充作⽤；
?limit=10 ：指定返回记录的数量 ?offset=10 ：指定返回记录的开始位置。 ?page=2&per_page=100 ：指定第⼏⻚，以及每⻚的记录数。 ?sortby=name&order=asc ：指定返回结果按照哪个属性排序，以及排序顺序。 ?animal_type_id=1 ：指定筛选条件
- 避免多级 URL，不利于扩展，语义也不明确，理解困难；
多级URL：
GET /authors/12/categories/2 // 含义是什么？
正确做法是：
GET /authors/12?categories=2
十、状态码
HTTP 状态码就是⼀个三位数，分成五个类别：
除非是 500 和 404 错误，⼤部分使⽤ 200 状态码即可，返回的数据格式如下：
十一、 其它
（1）API的⾝份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
