RESTful Web Service

一、REST：表述性状态转移

1、特点：客户端-服务器的、无状态的、可缓存的、统一接口的、分层系统、按需编码。

2、优势：跨平台、跨语言。

3、REST是一种架构风格。在这种架构风格中，对象被视为一种资源，通常使用概念清晰的名词命名。

4、表述性状态：指资源在某个瞬时的状态快照。资源可以有多种表述，表述状态具有描述性，包括资源数据的内容、表述格式（XML、JSON等）信息。

5、REST的资源是可寻址的，通过HTTP定义的通用动词方法(GET、PUT、DELETE、POST)，使用URI协议来唯一标识某个资源公布出来的接口。

• URI：统一资源标识符
• URL：统一资源定位符

6、请求一个资源的过程可以理解为访问一个具有指定性和描述性的URI，通过HTTP协议，将资源的表述从服务器“转移”到客户端或者相反方向。

7、基本实现：HTTP+URI+XML。HTTP协议和URI用于定位统一接口和定位资源，文本、二进制流、XML、JSON等格式用来作为资源的表述。

二、REST服务

1、概念：RESTful对应的中文是REST式的，RESTful Web Service的精准翻译应该是REST式的Web服务，通常简称为REST服务。

2、REST服务是一种ROA（面向资源的架构）应用。主要特点是：方法信息存在于HTTP协议的方法中（GET、PUT），作用域存在于URI中。

例子：在一个获取设备资源列表的GET请求中，方法信息式GET，作用域信息是URI中包含的对设备资源的过滤、分页、排序。

3、REST服务与传统Web Services的不同：

3.1、对比RCP风格：

• 方法信息：REST采用标准的HTTP方法；RCP请求的都是HTTP协议的POST方法，其方法信息包含于SOAP协议或者HTTP协议包中，方法名称不具有通用性。
• 作用域：REST采用URI显示定义作用域；RCP的作用域仍包含在协议包中，不能直观呈现。

3.2、对比大Web服务

大Web服务是基于RCP风格的重量设计，因此方法和作用域无法直观显示，需要定义在消息中，而且方法名不是统一和通用的。同时，大Web走HTTP协议时，请求都是基于POST方法的。

3.3、对比MVC风格

MVC很难实现跨语言的解耦，REST服务可以跨语言。Spring的MVC已经开始支持REST式的开发。

三、REST API设计

统一接口   

1、HTTP方法的安全性和幂等性：

• 安全性：指外系统对该接口的访问，不会使服务器端资源的状态发生改变。
• 幂等性：指外系统对同一REST接口的多次访问，得到的资源状态是相同的。

方法	作用	安全性	幂等性
GET	（读）获取服务提供的资源	安全	幂等
PUT	（写）更新或添加资源	不安全	幂等
DELETE	删除资源	不安全	幂等
POST	（写）添加资源	不安全	不幂等

 

 

 

 

 

 

2、添加资源时，何时使用PUT，何时使用POST？

 相同的数据每次提交到服务器端，都会为数据添加一个新的主键值，也就是创建一个主键值不一样的新资源，所以创建操作通常应当设计为POST方法的API；如果客户端在发起请求时，在同一份数据中总可以提供唯一的主键值，就可以使用PUT方法来设计API。

资源定位

REST使用URI实现资源定位，对外提供REST式的Web服务的接口就是公布一些列的URI及其参数。

实现资源定位就是要设计资源地址，资源地址的设计过程是面向资源的，资源名称应是准确描述该资源的名词，资源地址应具有直观的描述性。

注意：一个URI资源地址唯一对应一个资源，但是一个资源可以拥有多个URI资源地址。

1、资源地址的作用：资源地址的设计对整个REST式的Web服务至关重要，设计系统的可用性、可维护性和可扩展性等多方面的表现。

2、资源地址：scheme://host:port/path?queryString

元素	描述
scheme	协议名称，通常是http和https
host	主机名或者IP地址
port	服务端口
path	资源地址，使用“/”符号来分割逻辑上的层次结构
？	用来分隔资源地址和查询字符串符合
queryString	查询字符串，方法作用域信息 使用“&”符号来分隔查询条件 使用逗号分隔有次序的作用域信息 使用分号分隔无次序的作用域信息

 

 

 

 

 

 

 

 

 

3、资源地址是否可以唯一定位一个资源？否

不可以，资源地址相同，但HTTP方法不同的两个方法是两个不同的REST接口。HTTP方法和资源地址结合在一起才可以完成对资源的定位。

4、对于一个资源来说，除了基本的CRUD之外，还有其他的更新操作接口时，单单公布一个PUT方法就不够用了。所以，在路径变量难以准确描述的情况下，一种方案时可以考虑使用动词作为查询参数；另一种方案就是在REST设计过程中引入RCP风格的POST方法，辅助完成复杂业务的接口设计，这就是REST和RCP混合型的Web服务了。 

5、常用的资源地址设计示例：

功能	资源地址
查询全部	GET /books
主键查询	GET /books/{id} GET /books?id=12345678
分页作用域查询	GET /books?start=0&size=0 GET /books/01,2002-12,2004 GET /books/restful;program=java;type=web GET /books?limit=100&sort=bookname
修改/更新	PUT /books/{id}
删除	DELETE /books/{id}
添加/创建	POST /books PUT /books/{id}

 

 

 

 

 

 

 

 

 

 

传输格式 —— 即：表述

        如何设计表述，及传输过程中数据采用什么样的数据格式。通常REST接口会以XML和JSON作为主要的传输格式。

处理响应

       REST的响应处理结果应包括响应头中的HTTP状态码，响应实体中媒体参数类型和返回值类型，以及异常情况处理。

返回值类型：

• 无返回值void
• Response类实例
• 通用实体类型GenericEntity
• 自定义实例（File、String、更常用的是POJO类型）