RESTFul API 基础参考手册

本文提供了RESTFul API的基础知识，包括RESTFul API的基本概念，HTTP协议相关知识，Spring对REST的支持等。

REST介绍

REST不是什么

以信息为中心的表述性状态转移（Representational State Transfer，REST）已成为替换传统SOAP Web服务的流行方案。他们的主要区别是，SOAP一般会关注行为和处理，而REST关注的是要处理的数据。

REST不是“基于URL的Web服务”，也不是另一种类型的远程过程调用（remote procedure call，RPC）机制。RPC是面向服务的，并关注于行为和动作；而REST是面向资源的，强调描述应用程序的事物和名词。

REST是什么

RE-表述性（Representational）：REST资源实际上可以用各种形式来进行表述，包括XML、JSON（JavaScript Object Notation）甚至HTML——最适合资源使用者的任意形式。

S-状态（State）：当使用REST的时候，我们更关注资源的状态而不是对资源采取的行为。

T-转移（Transfer）：REST涉及到转移资源数据，它以某种表述性形式从一个应用转移到另一个应用。

简单来说，REST就是将资源的状态以最适合客户端或服务端的形式从服务器端转移到客户端（或者反过来）

REST中的资源

在REST中，资源通过URL进行识别和定位。至于RESTful URL的结构并没有严格的规则，但是URL应该能够识别资源，而不是简单的发一条命令到服务器上。再次强调，关注的核心是事物，而不是行为。

REST中的资源所指的不是数据，而是数据和表现形式的组合，比如“最新访问的10位会员”和“最活跃的10位会员”在数据上可能有重叠或者完全相同，而由于他们的表现形式不同，所以被归为不同的资源。

REST中的状态

REST中会有行为，它们是通过HTTP方法来定义的。具体来讲，也就是GET、POST、PUT、DELETE、PATCH以及其他的HTTP方法构成了REST中的动作。

这些HTTP方法通常会匹配为如下的CRUD动作：

• Create：POST
• Read：GET
• Update：PUT或PATCH
• Delete：DELETE

尽管通常来讲，HTTP方法会映射为CRUD动作，但这并不是严格的限制。有时候，PUT可以用来创建新资源，POST可以用来更新资源。实际上，POST请求非幂等性（non-idempotent）的特点使其成为一个非常灵活的方法，对于无法适应其他HTTP方法语义的操作，它都能够胜任。

REST与HTTP

HTTP Headers

HTTP头信息提供了关于请求，响应或者其他的发送实体的信息。

HTTP的头信息包括通用头、请求头、响应头和实体头四个部分。每个头域由一个域名，冒号（:）和域值三部分组成。

• 通用头标：即可用于请求，也可用于响应，是作为一个整体而不是特定资源与事务相关联。
• 请求头标：允许客户端传递关于自身的信息和希望的响应形式。
• 响应头标：服务器和于传递自身信息的响应。
• 实体头标：定义被传送资源的信息。即可用于请求，也可用于响应。

HTTP Request Header

请求头：

HTTP Responses Header

响应头:

HTTP Request Method

HTTP Request Method共计15种：

其中我们常用的POST请求数据被包含在请求体中，POST请求可能会导致新的资源的建立 和/或 已有资源的修改。

HTTP Status Code

HTTP状态码（英语：HTTP Status Code）是用以表示网页服务器超文本传输协议响应状态的3位数字代码。

HTTP状态码的第一个数字代表了响应的五种状态之一:

根据RFC7231规范，目前有以下HTTP状态码：

HTTP Content-type

Content-Type，内容类型，一般是指网页中存在的Content-Type，用于定义网络文件的类型和网页的编码，决定浏览器将以什么形式、什么编码读取这个文件。

比如输出图片文件、JSON数据、XML文件等非HTML内容时，就必须用header函数来指定Content-Type，才能达到输出一张图片或是其它指定内容类型的需求。

下面列举一些常用的内容类型：

REST与Spring

Spring很早就有导出REST资源的需求。Spring对REST的支持是构建在Spring MVC之上的。从3.0版本开始，Spring针对Spring MVC的一些增强功能对REST提供了良好的支持。

Spring4.0 REST特性

4.0版本中，Spring支持以下方式来创建REST资源：

• 控制器可以处理所有的HTTP方法，包含四个主要的REST方法：GET、PUT、DELETE以及POST。

package org.springframework.web.bind.annotation;
/**
 * Java 5 enumeration of HTTP request methods. 
 * @since 2.5
 */
public enum RequestMethod {
	GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE
}
复制代码

• Spring 3.2及以上版本还支持PATCH方法。

• 借助@PathVariable注解，控制器能够处理参数化的URL（将变量输入作为URL的一部分）。

• 借助Spring的视图和视图解析器，资源能够以多种方式进行表述，包括将模型数据渲染为XML、JSON、Atom以及RSS的View实现。

• 可以使用ContentNegotiatingViewResolver来选择最适合客户端的表述。

• 借助@ResponseBody注解和各种HttpMethodConverter实现，能够替换基于视图的渲染方式。

• @RequestBody注解以及HttpMethodConverter实现可以将传入的HTTP数据转化为传入控制器处理方法的 Java 对象。

• 借助RestTemplate，Spring应用能够方便地使用REST资源。

• 通过ResponseEntity对象，可以封装HTTP返回的header、body和statusCode。