一、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类型)