Home Tags Posts tagged with "REST"

REST

0 46

REST简介 – loveis715 – 博客园 (cnblogs.com)

 

大纲:

一、文章介绍

二、REST的示例

  1. REST的五大约束
    • 使用客户/服务器模型
    • 层次化的系统
    • 无状态
    • 可缓存
    • 统一的接口(其有四大子约束)
      • 每个资源都拥有一个资源标识
      • 消息的自描述性
      • 资源的自描述性
      • HATEOAS

三、REST的定义

  1. 资源识别
    • 如何抽象资源(自顶向下)
    • 判断一个资源是主资源还是子资源(看它是否能独立地表示其具体含义)
    • 如何判断为REST服务所定义的资源是否合理
      • 我们需要考虑对该资源的CRUD是否有意义,从而验证资源的定义是否合理。
      • 其次,我们需要检查资源是否需要除CRUD之外的动词来操作。
      • 除此之外,我们还需要检查这些资源是否是被整体使用,创建和删除。

四、资源的URL设计

  1. URL的组成
    • 协议
    • 主机名和断开
    • 资源的相对路径
    • 请求参数
  2. 通过URL来表示资源
  3. 资源在URL中需要由单数表示还是复数表示
  4. 相对路径 vs. 请求参数

 

五、合适的动词

  1. PUT和POST
    • POST动词会在目标URI之下创建一个新的子资源
    • PUT则是根据请求创建或修改特定位置的资源
  2. 两者都有创建的含义,但是意义却不同。在决定到底是使用PUT还是POST来创建资源的时候,软件开发人员需要考虑一系列问题
    • 首先就是资源的ID是如何生成的。
    • 另外一个需要考虑的因素则是PUT的等幂性是否对REST系统的设计有所帮助。(这在网络丢包较为严重时是一个非常好的功能。反过来,在同一个URI上调用两次POST将可能创建两个独立的子资源。
    • 除此之外,还需要考虑是否将资源的创建和更新归结为一个API可以简化用户对REST服务的使用。(用户可以通过PUT动词来同时完成创建和更新一个资源这两种不同的任务。这样的好处在于简化了REST服务所提供的接口,但是反过来也让一个API执行了两种不同的任务,在一定程度上违反了API设计时每个API都需要有明确的意义这一原则。
  3. PUT和PATCH(两者之间的不同则在于PUT是对整个资源的更新,而PATCH则是对部分资源的更新。而该动词的局限性则在于对该动词的支持程度。

 

六、使用标志的状态码

七、选择适当的表示结构

八、负载的自描述性

九、无状态约束

十、Authentication

十一、版本管理

十二、性能

0 38

RESTful架构

一、背景

Roy Thomas Fielding在他2000年的博士论文中提出 Rest 这个词,他说,我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。

 

二、名称

Fielding将他对互联网软件的架构原则,定名为REST,即Representational State Transfer的缩写。我对这个词组的翻译是”表现层状态转化”。

如果一个架构符合REST原则,就称它为RESTful架构。

要理解RESTful架构,最好的方法就是去理解Representational State Transfer这个词组到底是什么意思,它的每一个词代表了什么涵义。如果你把这个名称搞懂了,也就不难体会REST是一种什么样的设计。

 

三、资源(Resources

REST的名称”表现层状态转化”中,省略了主语。”表现层”其实指的是”资源”(Resources)的”表现层”。

所谓”资源”,就是网络上的一个实体,或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务,总之就是一个具体的实在。你可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。

所谓”上网”,就是与互联网上一系列的”资源”互动,调用它的URI

补充:URI和URL的区别

URI = Universal Resource Identifier 统一资源标志符,用来标识抽象或物理资源的一个紧凑字符串。
URL = Universal Resource Locator 统一资源定位符,一种定位资源的主要访问机制的字符串,一个标准的URL必须包括:protocol、host、port、path、parameter、anchor。

四、表现层(Representation)

“资源”是一种信息实体,它可以有多种外在表现形式。我们把”资源”具体呈现出来的形式,叫做它的”表现层”(Representation)。

比如,文本可以用txt格式表现,也可以用HTML格式、XML格式、JSON格式表现,甚至可以采用二进制格式;图片可以用JPG格式表现,也可以用PNG格式表现。

URI只代表资源的实体,不代表它的形式。严格地说,有些网址最后的”.html”后缀名是不必要的,因为这个后缀名表示格式,属于”表现层”范畴,而URI应该只代表”资源”的位置。它的具体表现形式,应该在HTTP请求的头信息中用Accept和Content-Type字段指定,这两个字段才是对”表现层”的描述。

五、状态转化(State Transfer)

访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必涉及到数据和状态的变化。

互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生”状态转化”(State Transfer)。而这种转化是建立在表现层之上的,所以就是”表现层状态转化”。

客户端用到的手段,只能是HTTP协议。具体来说,就是HTTP协议里面,四个表示操作方式的动词:GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。

 

六、综述

综合上面的解释,我们总结一下什么是RESTful架构:

         (1)每一个URI代表一种资源;

  (2)客户端和服务器之间,传递这种资源的某种表现层;

  (3)客户端通过四个HTTP动词,对服务器端资源进行操作,实现”表现层状态转化”。

 

七、误区(1.URI含动词 2.URI加版本号)

RESTful架构有一些典型的设计误区。

最常见的一种设计错误,就是URI包含动词。因为”资源”表示一种实体,所以应该是名词,URI不应该有动词,动词应该放在HTTP协议中。

举例来说,某个URI是/posts/show/1,其中show是动词,这个URI就设计错了,正确的写法应该是/posts/1,然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的,你就应该把动作做成一种资源。比如网上汇款,从账户1向账户2汇款500元,错误的URI是:

  POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction,资源不能是动词,但是可以是一种服务:

  POST /transaction HTTP/1.1
  Host: 127.0.0.1
  
  from=1&to=2&amount=500.00

另一个设计误区,就是在URI中加入版本号

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo

因为不同的版本,可以理解成同一种资源的不同表现形式,所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分(参见Versioning REST Services):

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

 

传统方式操作资源

方式:

问题所在:

  • 之前的操作是没有问题的,大神认为是有问题的,有什么问题呢?你每次请求的接口或者地址,都在做描述,例如查询的时候用了queryUser,新增的时候用了saveUser ,修改的时候用了updateUser,其实完全没有这个必要,我使用了get请求,就是查询.使用post请求,就是新增的请求,PUT就是修改,delete就是删除,我的意图很明显,完全没有必要做描述,这就是为什么有了restful.

请求方式

定义:可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中,GET 用于查询资源,POST 用于创建资源,PUT 用于更新服务端的资源的全部信息,PATCH 用于更新服务端的资源的部分信息,DELETE 用于删除服务端的资源。

这里使用“用户”的案例进行回顾通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。

使用RestFul操作资源

  • 【GET】 /users # 查询用户信息列表
  • 【GET】 /users/1001 # 查看某个用户信息
  • 【POST】 /users # 新建用户信息
  • 【PUT】 /users/1001 # 更新用户信息(全部字段)
  • 【PATCH】 /users/1001 # 更新用户信息(部分字段)
  • 【DELETE】 /users/1001 # 删除用户信息

API设计风格基本规则

1.使用名词而不是动词

2.Get方法和查询参数不应该涉及状态改变

  • 使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态,不要使用GET 进行状态改变:

3.使用复数名词

  • 不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。

4. 使用子资源表达关系

  • 如果一个资源与另外一个资源有关系,使用子资源:

GET /cars/711/drivers/ 返回 car 711的所有司机 GET /cars/711/drivers/4 返回 car 711的4号司机

5.使用Http头声明序列化格式

  • 在客户端和服务端,双方都要知道通讯的格式,格式在HTTP-Header中指定

Content-Type 定义请求格式

Accept 定义系列可接受的响应格式

6.为集合提供过滤 排序 选择和分页等功能

  • Filtering过滤:

使用唯一的查询参数进行过滤:

GET /cars?color=red 返回红色的cars GET /cars?seats<=2 返回小于两座位的cars集合

7.版本化你的API

  • 使得API版本变得强制性,不要发布无版本的API,使用简单数字,避免小数点如2.5.

一般在Url后面使用?v

/blog/api/v1

8. 使用Http状态码处理错误

9.允许覆盖http方法

  • 一些代理只支持POST 和 GET方法, 为了使用这些有限方法支持RESTful API,需要一种办法覆盖http原来的方法。

使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.

 

 

个人对RESTFul架构的理解:首先要清楚,RESTFul架构不是一种标准,而是一种风格(也就是可以使用RESTFul风格,也可以使用其他风格),那怎么鉴别是否是RESTFul风格呢?

很简单,遵循REST原则的,就是RESTFul风格。那么什么是REST原则呢?

1.每一个URI代表一种资源;(注意区别URI和URL)

2.应用于客户端和服务器(C/S)之间的交互,并且体现在表现层(资源的呈现形式)

3.客户端通过四个HTTP动词,对服务器端资源进行操作,实现”表现层状态转化”(GET,PUT,POST,DELETE)

知道了RESTFul风格的特点,那么我们如何去实现RESTFul风格的编程?即怎么遵循RESTFul的API规范

1.URI中无动词,使用名词

2.GET不改变状态

3.名词区分单复数

4.子资源

5.使用Http头声明序列化格式

思考:文中提到HTTP是无状态的,怎么理解无状态?

理解HTTP的无状态 – Our home (yangbili.co)