浅谈RESTful风格下的API接口设计

前言

百度百科

RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用XML格式定义或JSON格式定义。 RESTFUL适用于移动互联网厂商作为业务使能接口的场景,实现第三方OTT调用移动网络资源的功能,动作类型为新增、变更、删除所调用资源。

理解

RESTful是一套通俗的约定和标准, 是协议通信的双方共同遵守的约定.
REST架构的核心便是REST : Representational State Transfer

  1. Resources (资源)

URI是每个资源地址的独一无二的识别符
资源可以简单的理解成互联网上的信息, 在具体的服务端可以将其理解成对象, entity实体, 数据库表内的一行数据, 在REST风格中可以将其等同于信息的最小载体, 而URI则是与每一个具体的信息的地址所一一对应. 显示/操作这一资源需要通过对这一资源对应的URI进行处理来达到相应的目的

  1. Representation(表现层)

在HTTP请求中, 请求头中的Accept/Content-Type等字段则表示了表现形式的要求
资源只代表信息的本体, 并不会表示信息的表现形式, 而信息的具体表现形式则为HTML/XML等. 通常所见的表现形式包括但不限于图片(jpg/png), 文本(txt/html/xml/json), 表格excel, 文档pdf等等.

  1. 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

  1. URI表示资源集合使用复数形式, 否则使用单数形式
  2. 每一个URI表示一个资源, 所以不能含有动词(除了http方法不能代表的动作)
  3. 避免层级过深的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的一些注意事项 - 简书

江湖梦

你可能感兴趣的:(浅谈,restful)