RESTful API 了解

1.REST概念

REST全称是Representational State Transfer。要理解RESTful架构,需要理解Representational State Transfer这个词组到底是什么意思,它的每一个词都有些什么涵义。下面我们结合REST原则,围绕资源展开讨论,从资源的定义、获取、表述、关联、状态变迁等角度,列举一些关键概念并加以解释。

  • 资源与URI
  • 统一资源接口
  • 资源的表述
  • 资源的链接
  • 状态的转移

2.RESTful API概念

在开发的过程中,我们经常会听到前后端分离这个技术名词,顾名思义,就是前台的开发和后台的开发分离开。这个技术方案的实现就是要借助API,API简单说就是开发人员提供编程接口被其他人调用,他们调用之后会返回数据供其使用。API的类型有多种,但是现在比较主流且实用的就是RESTful API。

RESTful API 的总结:
1.每一个URL代表一种资源
2.客户端和服务器之间,传递这种资源的某种表现层
3.客户端通过四个HTTP动词,对服务器端资源进行操作,实现”表现层状态转化”。具体为:
GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。

2.1 RESTful API方法-GET

  • 安全且幂等

  • 获取表示

  • 变更时获取表示(缓存)

  • 200(OK) - 表示已在响应中发出

  • 204(无内容) - 资源有空表示

  • 301(Moved Permanently) - 资源的URI已被更新

  • 303(See Other) - 其他(如,负载均衡)

  • 304(not modified)- 资源未更改(缓存)

  • 400 (bad request)- 指代坏请求(如,参数错误)

  • 404 (not found)- 资源不存在

  • 406 (not acceptable)- 服务端不支持所需表示

  • 500 (internal server error)- 通用错误响应

  • 503 (Service Unavailable)- 服务端当前无法处理请求

    2.2 RESTful API方法-POST

  • 不安全且不幂等

  • 使用服务端管理的(自动产生)的实例号创建资源

  • 创建子资源

  • 部分更新资源

  • 如果没有被修改,则不过更新资源(乐观锁)

  • 200(OK)- 如果现有资源已被更改

  • 201(created)- 如果新资源被创建

  • 202(accepted)- 已接受处理请求但尚未完成(异步处理)

  • 301(Moved Permanently)- 资源的URI被更新

  • 303(See Other)- 其他(如,负载均衡)

  • 400(bad request)- 指代坏请求

  • 404 (not found)- 资源不存在

  • 406 (not acceptable)- 服务端不支持所需表示

  • 409 (conflict)- 通用冲突

  • 412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)

  • 415 (unsupported media type)- 接受到的表示不受支持

  • 500 (internal server error)- 通用错误响应

  • 503 (Service Unavailable)- 服务当前无法处理请求

2.3 RESTful API方法-PUT

  • 不安全但幂等
  • 用客户端管理的实例号创建一个资源
  • 通过替换的方式更新资源
  • 如果未被修改,则更新资源(乐观锁)
  • 200 (OK)- 如果已存在资源被更改
  • 201 (created)- 如果新资源被创建
  • 301(Moved Permanently)- 资源的URI已更改
  • 303 (See Other)- 其他(如,负载均衡)
  • 400 (bad request)- 指代坏请求
  • 404 (not found)- 资源不存在
  • 406 (not acceptable)- 服务端不支持所需表示
  • 409 (conflict)- 通用冲突
  • 412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)
  • 415 (unsupported media type)- 接受到的表示不受支持
  • 500 (internal server error)- 通用错误响应
  • 503 (Service Unavailable)- 服务当前无法处理请求

2.4 RESTful API方法-DELETE

  • 不安全但幂等
  • 删除资源
  • 200 (OK)- 资源已被删除
  • 301 (Moved Permanently)- 资源的URI已更改
  • 303 (See Other)- 其他,如负载均衡
  • 400 (bad request)- 指代坏请求
  • 404 (not found)- 资源不存在
  • 409 (conflict)- 通用冲突
  • 500 (internal server error)- 通用错误响应
  • 503 (Service Unavailable)- 服务端当前无法处理请求

3.常见问题

  • POST和PUT用于创建资源时有什么区别?
    POST和PUT在创建资源的区别在于,所创建的资源的名称(URI)是否由客户端决定。 例如为我的博文增加一个java的分类,生成的路径就是分类名/categories/java,那么就可以采用PUT方法。不过很多人直接把POST、GET、PUT、DELETE直接对应上CRUD,例如在一个典型的rails实现的RESTful应用中就是这么做的。

我认为,这是因为rails默认使用服务端生成的ID作为URI的缘故,而不少人就是通过rails实践REST的,所以很容易造成这种误解。

  • 客户端不一定都支持这些HTTP方法吧?
    的确有这种情况,特别是一些比较古老的基于浏览器的客户端,只能支持GET和POST两种方法。

在实践上,客户端和服务端都可能需要做一些妥协。例如rails框架就支持通过隐藏参数_method=DELETE来传递真实的请求方法, 而像Backbone这样的客户端MVC框架则允许传递_method传输和设置X-HTTP-Method-Override头来规避这个问题。

  • 统一接口是否意味着不能扩展带特殊语义的方法?
    统一接口并不阻止你扩展方法,只要方法对资源的操作有着具体的、可识别的语义即可,并能够保持整个接口的统一性。

像WebDAV就对HTTP方法进行了扩展,增加了LOCK、UPLOCK等方法。而github的API则支持使用PATCH方法来进行issue的更新,例如:

PATCH /repos/:owner/:repo/issues/:number
不过,需要注意的是,像PATCH这种不是HTTP标准方法的,服务端需要考虑客户端是否能够支持的问题。

  • 统一资源接口对URI有什么指导意义?
    统一资源接口要求使用标准的HTTP方法对资源进行操作,所以URI只应该来表示资源的名称,而不应该包括资源的操作。

通俗来说,URI不应该使用动作来描述。例如,下面是一些不符合统一接口要求的URI:

GET /getUser/1
POST /createUser
PUT /updateUser/1
DELETE /deleteUser/1

4.RESTful API 应用

  • Django Rest framework

1.建立 Models
2.依靠 Serialiers 将数据库取出的数据 Parse 为 API 的数据(可用于返回给客户端,也可用于浏览器显示)
3.ViewSet 是一个 views 的集合,根据客户端的请求(GET、POST等),返回 Serialiers 处理的数据,权限 Premissions 也在这一步做处理
4.ViewSet 可在 Routers 进行注册,注册后会显示在 Api Root 页上
5.在 urls 里注册 ViewSet 生成的 view,指定监听的 url

# 推荐文章
  1.深刻理解Docker镜像大小
  2.k8s专题[1.k8s基础概念]
  3.k8s专题[10.使用Spinnaker持续发布应用]
  4.k8s专题[2.k8s设计原则]
  5.k8s专题[3.k8s基础组件]

评论


:D 一言句子获取中...