RESTful架构与接口设计

Representational state transfer (REST) or RESTful Web services are one way of providing interoperability between computer systems on the Internet.

—— WiKi

　　RESTful架构，就是目前最流行的一种互联网软件架构。它结构清晰、易于理解、扩展方便，更具有人性化，已经被越来越多的我们熟知的网站所采用。

1. 什么是REST原则
　　REST全称是Representational State Transfer，中文意思是表述性状态转移（表现层的状态转移）。 它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到：“我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。” 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

　　REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。

2. 理解RESTful
　　如果一个架构符合REST原则，就称它为RESTful架构。
　　要想理解Representational State Transfer这个词组到底是什么意思，它的每一个词都有些什么涵义。

2.1 资源（Resources）
　　
　　REST的名称“表现层状态转化”中，省略了主语。“表现层”指的是什么的表述？其实指的就是资源（Resource）。
　　任何事物，只要有被引用到的必要，它就是一个资源。资源可以是实体（例如手机号码），也可以只是一个抽象概念（例如价值） 。下面是一些资源的例子：

　　- 某用户的手机号码
　　- 某用户的个人信息
　　- 用户订购的商品
　　- 两个产品之间的依赖关系
　　- 某用户可以办理的优惠套餐
　　- 某股票的潜在价值

　　要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI（Uniform Resource Identifier），它是网络上的一个实体，或者说是网络上的一个具体信息，它可以是一段文本、一张图片、一首歌曲、一种服务等。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。我们平时访问一个网站，就是与互联网上一系列的“资源”进行互动，调用了它的URI。
　　URI既可以看成是资源的地址，也可以看成是资源的名称。如果某些信息没有使用URI来表示，那它就不能算是一个资源， 只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则，具有自描述性，需要在形式上给人以直觉上的关联。这里以github网站为例，给出一些还算不错的URI：

　　- https://github.com/git
　　- https://github.com/git/git
　　- https://github.com/git/git/pulls
　　- https://github.com/git/git/pulls?state=closed
　　- https://github.com/git/git/blob/master/block-sha1/sha1.h
　　- https://github.com/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08
　　- https://github.com/git/git/compare/master…next

　　下面让我们来看看URI设计上的一些技巧：
　　
　　1） 使用_或-来让URI可读性更好
　　曾经Web上的URI都是冰冷的数字或者无意义的字符串，但现在越来越多的网站使用_或-来分隔一些单词，让URI看上去更为人性化。 例如国内比较出名的开源中国社区，它上面的新闻地址就采用这种风格， 如http://www.oschina.net/news/38119/oschina-translate-reward-plan。
　　
　　2） 使用/来表示资源的层级关系
　　例如上述/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08就表示了一个多级的资源， 指的是git用户的git项目的某次提交记录，又例如/orders/2012/10可以用来表示2012年10月的订单记录。
　　
　　3） 使用?用来过滤资源
　　很多人只是把?简单的当做是参数的传递，很容易造成URI过于复杂、难以理解。可以把?用于对资源的过滤， 例如/git/git/pulls用来表示git项目的所有推入请求，而/pulls?state=closed用来表示git项目中已经关闭的推入请求， 这种URL通常对应的是一些特定条件的查询结果或算法运算结果。
　　
　　4） ,或;可以用来表示同级资源的关系
　　有时候我们需要表示同级资源的关系时，就可以使用,或;来进行分割。例如某一天GitHub可以比较某个文件在随意两次提交记录之间的差异，或许可以使用/git/git/block-sha1/sha1.h/compare/e3af72cdafab5993d18fae056f87e1d675913d08;bd63e61bdf38e872d5215c07b264dcc16e4febca作为URI。 不过，现在github是使用…来做这个事情的，例如/git/git/compare/master…next。

2.2 资源的表述（Representation）
　　我们把“资源”具体呈现出来的形式，叫做它的“表现层”（Representation）。
　　
　　资源在外界的具体呈现，可以有多种表述(或成为表现、表示)形式，在客户端和服务端之间传送的也是资源的表述，而不是资源本身。客户端获取的只是资源的表述而已。
　　比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。
　　资源的表述包括数据和描述数据的元数据，例如，HTTP头“Content-Type” 就是这样一个元数据属性。
　　
　　URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的“.html”后缀名是不必要的，因为这个后缀名表示格式，属于“表现层”范畴，而URI应该只代表“资源”的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对“表现层”的描述。

　　那么客户端如何知道服务端提供哪种表述形式呢?
　　答案是可以通过HTTP内容协商，客户端可以通过Accept头请求一种特定格式的表述，服务端则通过Content-Type告诉客户端资源的表述形式。
　　以GitHub为例，请求某组织资源的Json格式的表述形式：
　　

　　假如是xml则结果是这样的：
　　

下面我们来看一些实践上常见的设计：

　　1） 在URI里边带上版本号
　　有些API在URI里边带上版本号，例如:
　　- http://api.example.com/1.0/foo
　　- http://api.example.com/1.2/foo
　　- http://api.example.com/2.0/foo
　　如果我们把版本号理解成资源的不同表述形式的话，就应该只是用一个URL，并通过Accept头部来区分，还是以github为例，它的Accept的完整格式是:application/vnd.github[.version].param[+json]

　　对于v3版本的话，就是Accept: application/vnd.github.v3。对于上面的例子，同理可以使用使用下面的头部:
　　- Accept: vnd.example-com.foo+json; version=1.0
　　- Accept: vnd.example-com.foo+json; version=1.2
　　- Accept: vnd.example-com.foo+json; version=2.0

　　2） 使用URI后缀来区分表述格式
　　像rails框架，就支持使用/users.xml或/users.json来区分不同的格式。 这样的方式对于客户端来说，无疑是更为直观，但混淆了资源的名称和资源的表述形式。

　　3） 如何处理不支持的表述格式
　　当服务器不支持所请求的表述格式，那么应该怎么办？若服务器不支持，它应该返回一个HTTP 406响应，表示拒绝处理该请求。下面以github为例，展示了一个请求XML表述资源的结果：
　　

2.3 状态转化（State Transfer）
　　互联网通信的HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生”状态转化”（State Transfer）。

　　2.3.1 应用状态和资源状态
　　实际上，状态应该区分应用状态和资源状态，客户端负责维护应用状态，而服务端维护资源状态。 客户端与服务端的交互必须是无状态的，并在每一次请求中包含处理该请求所需的一切信息。 服务端不需要在请求间保留应用状态，只有在接受到实际请求的时候，服务端才会关注应用状态。 这种无状态通信原则，使得服务端和中介能够理解独立的请求和响应。 在多次请求中，同一客户端也不再需要依赖于同一服务器，方便实现高可扩展和高可用性的服务端。

　　但有时候我们会做出违反无状态通信原则的设计，例如利用Cookie跟踪某个服务端会话状态，常见的像J2EE里边的JSESSIONID。 这意味着，浏览器随各次请求发出去的Cookie是被用于构建会话状态的。 当然，如果Cookie保存的是一些服务器不依赖于会话状态即可验证的信息（比如认证令牌），这样的Cookie也是符合REST原则的。

　　2.3.2 采用的手段
　　客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词（括号里是对应的SQL命令）：GET（SELECT）、POST（CREATE）、PUT（UPDATE）、DELETE（DELETE）。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

　　下面列出了GET，DELETE，PUT和POST的典型用法：

GET

安全且幂等
获取表示
变更时获取表示（缓存）
200（OK） - 表示已在响应中发出
301（Moved Permanently） - 资源的URI已被更新
303（See Other） - 其他（如，负载均衡）
304（not modified）- 资源未更改（缓存）
400 （bad request）- 指代坏请求（如，参数错误）
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
500 （internal servererror）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

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）- 服务当前无法处理请求

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）- 服务当前无法处理请求

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）- 服务端当前无法处理请求

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

　　2） 统一资源接口对URI有什么指导意义？
　　统一资源接口要求使用标准的HTTP方法对资源进行操作，所以URI只应该来表示资源的名称，而不应该包括资源的操作。 通俗来说，URI不应该使用动作来描述。例如，下面是一些不符合统一接口要求的URI:
　　GET /getUser/1
　　POST /createUser
　　PUT /updateUser/1
　　DELETE /deleteUser/1

　　3） 如果GET请求增加计数器，这是否违反安全性？
　　安全性不代表请求不产生副作用，例如像很多API开发平台，都对请求流量做限制。像github，就会限制没有认证的请求每小时只能请求60次。 但客户端不是为了追求副作用而发出这些GET或HEAD请求的，产生副作用是服务端“自作主张”的。 另外，服务端在设计时，也不应该让副作用太大，因为客户端认为这些请求是不会产生副作用的。

　　4） 直接忽视缓存可取吗？
　　即使你按各个动词的原本意图来使用它们，你仍可以轻易禁止缓存机制。 最简单的做法就是在你的HTTP响应里增加这样一个报头： Cache-control: no-cache。 但是，同时你也对失去了高效的缓存与再验证的支持(使用Etag等机制)。 对于客户端来说，在为一个REST式服务实现程序客户端时，也应该充分利用现有的缓存机制，以免每次都重新获取表示。

　　5） 响应码的处理有必要吗？
　　HTTP的响应代码可用于应付不同场合，正确使用这些状态代码意味着客户端与服务器可以在一个具备较丰富语义的层次上进行沟通。 例如，201（“Created”）响应代码表明已经创建了一个新的资源，其URI在Location响应报头里。 假如你不利用HTTP状态代码丰富的应用语义，那么你将错失提高重用性、增强互操作性和提升松耦合性的机会。 如果这些所谓的RESTful应用必须通过响应实体才能给出错误信息，那么SOAP就是这样的了，它就能够满足了。

参考文章：
【1】http://kb.cnblogs.com/page/512047/
【2】http://www.ruanyifeng.com/blog/2011/09/restful.html
（经过整理，本文仅作学习使用）