浅谈RESTful风格下的API接口设计
前言
百度百科
RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用XML格式定义或JSON格式定义。 RESTFUL适用于移动互联网厂商作为业务使能接口的场景,实现第三方OTT调用移动网络资源的功能,动作类型为新增、变更、删除所调用资源。
理解
RESTful是一套通俗的约定和标准, 是协议通信的双方共同遵守的约定.
REST架构的核心便是REST : Representational State Transfer
- Resources (资源)
URI是每个资源地址的独一无二的识别符
资源可以简单的理解成互联网上的信息, 在具体的服务端可以将其理解成对象, entity实体, 数据库表内的一行数据, 在REST风格中可以将其等同于信息的最小载体, 而URI则是与每一个具体的信息的地址所一一对应. 显示/操作这一资源需要通过对这一资源对应的URI进行处理来达到相应的目的
- Representation(表现层)
在HTTP请求中, 请求头中的Accept/Content-Type等字段则表示了表现形式的要求
资源只代表信息的本体, 并不会表示信息的表现形式, 而信息的具体表现形式则为HTML/XML等. 通常所见的表现形式包括但不限于图片(jpg/png), 文本(txt/html/xml/json), 表格excel, 文档pdf等等.
- State Transfer(状态转换)
在HTTP请求中, 随着信息的交换, 一定伴随着状态的转换
HTTP是一种无状态的协议, 在通信的过程中, 并不会携带具体的状态信息, 所有的状态信息都会保存在服务端, 如果需要操作具体的资源, 则需要更改资源的状态信息. 而这种转换是建立在"表现层"上面的, 就是所谓的"表现层状态转换".
HTTP的动作对应资源的操作形式. GET/POST/PUT/DELETE
一个奇怪的理解
资源 --> html(看的啥)
表现层 --> css(咋看)
状态装换 --> js(动画/状态改变)
疑问
- 通过操作资源的表现形式来操作资源? 这句话怎么理解?
- 表现层状态转化 为什么这么命名?
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规范/约定
- 禁止大写
- 如需用 - ,用 - , 不用 _
- 编码格式要encode
decode encode
str ---------> unicode --------->str
- URI表示资源集合使用复数形式, 否则使用单数形式
- 每一个URI表示一个资源, 所以不能含有动词(除了http方法不能代表的动作)
- 避免层级过深的URI, 否则会引起URI膨胀, 不宜维护
状态码
§200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
§201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
§202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
§204 NO CONTENT - [DELETE]:用户删除数据成功。
§400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
§401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
§403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
§404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
§406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
§410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
§422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
§500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
cr:
HTTP方法的幂等性与安全性
理解RESTful架构 - 阮一峰的网络日志
表现层转换 - *
RESTful的一些注意事项 - 简书
本文地址:https://blog.****.net/deng550/article/details/107371573
上一篇: 计算机程序的构造和解释 练习题3.5