浅谈RESTful风格下的API接口设计
## 前言#### 百度百科
> RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。 RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。
#### 理解
**RESTful是一套通俗的约定和标准, 是协议通信的双方共同遵守的约定.
REST架构的核心便是REST : Representational State Transfer**
1.Resources (资源)
**URI是每个资源地址的独一无二的识别符**
资源可以简单的理解成互联网上的信息, 在具体的服务端可以将其理解成对象, entity实体, 数据库表内的一行数据, 在REST风格中可以将其等同于信息的最小载体, 而URI则是与每一个具体的信息的地址所一一对应. 显示/操作这一资源需要通过对这一资源对应的URI进行处理来达到相应的目的
2. Representation(表现层)
**在HTTP请求中, 请求头中的Accept/Content-Type等字段则表示了表现形式的要求**
资源只代表信息的本体, 并不会表示信息的表现形式, 而信息的具体表现形式则为HTML/XML等. 通常所见的表现形式包括但不限于图片(jpg/png), 文本(txt/html/xml/json), 表格excel, 文档pdf等等.
3.State Transfer(状态转换)
**在HTTP请求中, 随着信息的交换, 一定伴随着状态的转换**
HTTP是一种无状态的协议, 在通信的过程中, 并不会携带具体的状态信息, 所有的状态信息都会保存在服务端, 如果需要操作具体的资源, 则需要更改资源的状态信息. 而这种转换是建立在"表现层"上面的, 就是所谓的"表现层状态转换".
HTTP的动作对应资源的操作形式. GET/POST/PUT/DELETE
> **一个奇怪的理解**
> 资源 --> html(看的啥)
> 表现层 --> css(咋看)
> 状态装换 --> js(动画/状态改变)
#### 疑问
1. 通过操作资源的表现形式来操作资源? 这句话怎么理解?
2. 表现层状态转化 为什么这么命名?
#### HTTP相关
符合REST设计风格的Web API称为RESTful API。它从以下三个方面资源进行定义：
- 直观简短的资源地址：URI，比如：http://example.com/resources
- 传输的资源：Web服务接受与返回的互联网媒体类型，比如：JSON，XML，YAML等
- 对资源的操作：Web服务在该资源上所支持的一系列请求方法（比如：POST，GET，PUT或DELETE）
#####一个表表示一下区别
|URI|GET|PUT|POST|DELETE|
|--|--|--|--|--|
http:xxx.com/resources|获得改资源组的详细信息|使用给定的一组资源替换当前整组资源|在本组资源中创建/追加一个新的资源|删除整组资源
http:xxx.com/resource/1|获得改资源为1的详细信息|替换/创建指定的资源。并将其追加到相应的资源组中|把指定的资源当做一个资源组，并在其下创建/追加一个新的元素，使其隶属于当前资源|删除为1的资源
## HTTP方法的选用标准
**要严格按照安全性和幂等性的要求来选用HTTP的方法**
- 安全性: 不改变资源
- 幂等性: 多次执行的结果一样
| \ | GET | PUT | POST | DELETE | HEAD | PATCH |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: |
安全性 | √ | × | × | × | √ | ×
幂等性 | √ | √ | × | √ | √ | ×
## URI规范/约定
1. 禁止大写
2. 如需用 - ,用 - , 不用 _
3. 编码格式要encode
> decode encode
str ---------> unicode --------->str
4. URI表示资源集合使用复数形式, 否则使用单数形式
5. 每一个URI表示一个资源, 所以不能含有动词(除了http方法不能代表的动作)
6. 避免层级过深的URI, 否则会引起URI膨胀, 不宜维护
## 状态码
```shell
§200 OK - ：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
§201 CREATED - ：用户新建或修改数据成功。
§202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
§204 NO CONTENT - ：用户删除数据成功。
§400 INVALID REQUEST - ：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
§401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
§403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
§404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
§406 Not Acceptable - ：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
§410 Gone -：用户请求的资源被永久删除，且不会再得到的。
§422 Unprocesable entity - 当创建一个对象时，发生一个验证错误。
§500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
```
> cr:
> (https://icbd.github.io/wiki/notes/2018/01/16/http-safe-idempotent.html)
> [理解RESTful架构 - 阮一峰的网络日志](https://www.ruanyifeng.com/blog/2011/09/restful.html)
> [表现层转换 - 维基百科](https://zh.wikipedia.org/wiki/%E8%A1%A8%E7%8E%B0%E5%B1%82%E7%8A%B6%E6%80%81%E8%BD%AC%E6%8D%A2)
> (https://www.jianshu.com/p/b531519fe813) 感谢分享 put 和 post 是有争议的，如果是添加都是没有幂等性的，如果修改是有的。 现在有的人put增加 post修改，有的人post增加，put修改。 所以emm LeagueJinx 发表于 2021-3-26 17:17
put 和 post 是有争议的，如果是添加都是没有幂等性的，如果修改是有的。 现在有的人put增加 post修改，有 ...
感觉现在很多人在写api的时候都没有研究过put和post的差别，都是拿来即用
缺少了语义性的约束
还有的是get转post的那种，例如参数过多/安全要求/自定义协议等等，都有各自的使用场景
感觉更多的是对自身的思考吧 对的。，只使用get post的大有人在，，还有全post的，。。 多学一点有好处，有助于自己技术的更新提升
页:
[1]