PDF下载地址：https://download.csdn.net/download/weixin_45525272/80429647
文章目录RESTful API设计规范
⼀、什么是RESTful？二、设计概念和准则三、为什么要使用RESTful API？四、协议五、域名六、版本七、http请求⽅式八、路由（路径）九、过滤信息（url中?后⾯的参数）
使用过滤信息的原因： 十、状态码十一、 其它
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部署在专⽤域名之下：
https://api.example.com
如果确定API很简单，不会有进⼀步扩展，可以考虑放在主域名下：
六、版本https://example.org/api/
在每个API对应的URL中，应有⼀个版本号，以便将来服务升级后，所有版本的客户端可以正常使用，如下：
七、http请求⽅式https://api.example.com/v1/topics/
https://api.example.com/v2/topics/
https://api.example.com/v3/topics/
| 请求方式 | 含义 |
|---|---|
| GET | 读取（Read） |
| POST | 新建（Create） |
| PUT | 更新（Update），通常是全部更新 |
| PATCH | 更新（Update），通常是部分更新 |
| DELETE | 删除（Delete） |
• 每个⽹址中不能有动词，只能有名词。并且应该使⽤复数，除⾮没有合适的复数形式，如：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的⽤户名下所有帖⼦
• 更多例子[带请求方法]
九、过滤信息（url中?后⾯的参数） 使用过滤信息的原因：[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 路径不能表现出所有的场景的，起到了补充作⽤；
?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 状态码就是⼀个三位数，分成五个类别：
| 类别 | 含义 |
|---|---|
| 1xx | 相关信息，不使用 |
| 2xx | 操作成功 |
| 3xx | 重定向 |
| 4xx | 客户端错误 |
| 5xx | 服务器错误 |
除非是 500 和 404 错误，⼤部分使⽤ 200 状态码即可，返回的数据格式如下：
（1）API的⾝份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
