RESTful架构与RESTful API设计

一、REST的由来

　　REST这个词是Roy Thomas Fielding博士在他2000年的博士论文中提出的，Fielding将他对互联网软件的架构原则定名为REST，即Representational State Transfer的缩写，翻译为“表现层状态转化”。如果一个架构符合REST原则，就称它为RESTful架构，即REST风格的架构。

二、REST是什么

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

资源（Resources）

　　REST的名称“表现层状态转化”中省略了主语。“表现层”其实是指的“资源（Resources）”的“表现层”。
　　所谓“资源”，就是网络上的一个实体，或者是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务、总之就是一个具体的实体。你可以用一个URI（统一资源标识符）指向它，每种资源对应一个特定的URL。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

表现层（Representation）

　　“资源”是一种信息实体，他可以有多种的外在表现形式。我们把“资源”具体呈现出来的形式称之为“表现层”。比如：文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式表现；图片可以采用JPG格式表现，也可以用PNG格式表现。
　　URI只代表资源的实体，不代表他的形式。严格地说，有些网址最后的“.html”后缀名是不必要的，因为这个后缀名表示格式，属于“表现层”的范畴，而URI应该只代表“资源”的位置。它的具体表现形式应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对“表现层”的描述，不过在大部分应用中，通过后缀区分表现层就已经足够了。

状态转化（State Transfer）

　　访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及数据和状态的变化。
　　HTTP协议是一个无状态互联网通信协议，这意味着所有状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器发生“状态转化（State Transfer）”。而这种转化是建立在表现层之上的，所以就叫做“表现层状态转化”。
　　客户端用到的手段只能是HTTP协议。具体的说，HTTP协议里有5个常用的表示操作方式的动词：GET、POST、PUT、DELETE、PATCH。它们分别对应5种基本操作：GET用来获取资源，POST用来新建资源（也可以用来更新资源），PUT用来更新资源，DELETE用来删除资源，PATCH用来更新资源的部分属性。

三、RESTful架构

　　现在流行的各种Web框架，包括Spring Boot都支持REST开发，REST并非是一种技术或者规范，而是一种架构风格，这种架构风格逐渐各种编程语言的Web框架所支持。它包括了REST架构中如何标识资源，如何表示操作接口及操作版本，如何标识操作结果等，主要内容如下：

• 使用“api”作为Web上下文；
• 增加版本标识；
• 标识资源；
• REST中的HTTP Method；
• REST中的HTTP Status；

1）使用“api”作为上下文：

http://192.168.0.1/api

　　也有的使用“api”作为二级域名：

http://api.XXXX.com

2）增加一个版本标识

http://192.168.0.1/api/v1.1

　　也有的做法是将版本信息放到HTTP头，但这里推荐还是通过URl来实现，这样使得REST的相关代码更加容易阅读。

3）标识资源

　　将资源名称放到URL中，如果资源有层级关系，则放入层级关系：

http://192.168.0.1/api/v1.1/user

　　如果用户属于系统管理，也可以这么写：

http://192.168.0.1/api/v1.1/system/user

4）确定HTTP Method

　　在REST中，HTTP Method常常对应一下含义：

• POST：代表增加资源；
• PUT：代表更改资源，客户端提供完整的资源属性；
• GET：代表查询资源；
• PATCH:更新资源，客户端提供仅需要更改的资源属性；
• DELETE:通常用于删除资源；
• HEAD：类似GET，但仅仅只有HTTP头信息，头信息中包含了需要查找的信息；
• OPTIONS，用于获取URI所支持的方法，相应信息会在HTTP头中包含一个名为“Allow”的头，值是所支持的方法，如“GET、POST”；

在业务系统中，删除往往并不是指的物理删除，而是逻辑删除，资源通常仍在数据库中，只是状态设置为删除状态。

RESTful API设计的一些例子
新增用户：

POST：http://192.168.0.1/api/v1.1/system/user

查询id为45的用户

GET：http://192.168.0.1/api/v1.1/system/user/45

查询所有用户：

GET：http://192.168.0.1/api/v1.1/system/user

如果有翻页，可以在后面增加类似offset、limit参数，比如：

GET：http://192.168.0.1/api/v1.1/system/user?offset=1&limit=20&sortBy=name

更新用户id为45的用户：

PUT：http://192.168.0.1/api/v1.1/system/user/45

删除用户id为45的用户：

DELETE：http://192.168.0.1/api/v1.1/system/user/45

注意：可以为资源标识添加后缀，使得REST代码更加容易阅读，比如：

GET： http://192.168.0.1/api/v1.1/system/user/45.json

返回id为45的用户信息，返回格式是json

5）确定HTTP Status

　　服务器向客户端返回HTTP Status以表示操作是否成功，常用的如下：

• 200，OK，用户请求成功，如查询数据成功返回。
• 400，错误的请求。
• 404　，NOT　Found，用户发出的请求针对的资源不存在，通常是Spring　Boot中的Controller没有匹配上URI，或者匹配上了Controller方法，但是渲染的视图不存在。
• 405，用来访问本页面的HTTP Method不被允许。
• 406，表示无法使用请求的内容特性来相应请求资源，比如在Spring Boot中，请求后缀以html结尾，但同时请求的HTTP头中又包含Accept:application/json。
• 500，服务器内部错误，无法完成请求，通常是Controller抛出的异常。

四、RESTful总结

　　1）每一个URI代表一种资源。
　　2）客户端和服务器之间传递这种资源的表现层。
　　3）客户端通过HTTP动词，对服务器端资源进行操作，实现“表现层状态转化”。
　　一句话概括：URI定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

五、REST VS. WebService

　　REST和WebService主要的差别就是前者是一种轻量级的架构，而后者是一种重量级架构。前者即适合终端到服务的调用，系统内部子系统的互相调用，也适合不同公司之间的系统互相调用，而WebService较为适合不同公司之间系统的调用。
　　注：有不明白WebService的同学请看下面的参考资料。

六、参考资料

　　理解RESTful架构
　　RESTful API 设计指南
　　
　　有关WebService的文章：
　　Web service是什么？
　　Web Service技术的SOAP实现
　　Web Services 系列教程
　　Web API知识
　　到底 REST 和 SOAP、RPC 有何区别？