理解RESTful架构

什么是REST

具象状态传输（英文：Representational State Transfer，简称REST）是Roy Thomas Fielding博士于2000年在他的博士论文 “Architectural Styles and the Design of Network-based Software Architectures” 中提出来的一种万维网软件架构风格。

这是Wiki上关于REST的解释。

要理解什么是REST，我们需要理解下面几个概念:

• 资源（Resources） REST是”表现层状态转化”，其实它省略了主语。”表现层”其实指的是”资源”的”表现层”。

  那么什么是资源呢？就是我们平常上网访问的一张图片、一个文档、一个视频等。这些资源我们通过URI来定位，也就是一个URI表示一个资源。

• 表现层（Representation）

  “资源”是一种信息实体，它可以有多种外在表现形式。我们把”资源”具体呈现出来的形式，叫做它的”表现层”（Representation）。

  比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

  URI只代表资源的实体，不代表它的形式。那如何确定它的具体表现形式呢？它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对”表现层”的描述。

• 状态转化（State Transfer）

  访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，肯定涉及到数据和状态的变化。而HTTP协议是无状态的，那么这些状态肯定保存在服务器端，所以如果客户端想要通知服务器端改变数据和状态的变化，肯定要通过某种方式来通知它。

  客户端能通知服务器端的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

综合上面的解释，我们总结一下什么是RESTful架构：

• 每一个URI代表一种资源；
• 客户端和服务器之间，传递这种资源的某种表现层；
• 客户端通过四个HTTP动词（GET/POST/PUT/DELETE），对服务器端资源进行操作，实现”表现层状态转化”。

RESTful API设计

理解了什么是RESTful架构，下面介绍RESTful API的设计细节，探讨如何设计一套合理、好用的API。

URI

要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI(Uniform Resource Identifier)。 URI既可以看成是资源的地址，也可以看成是资源的名称。如果某些信息没有使用URI来表示，那它就不能算是一个资源， 只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则，具有自描述性，需要在形式上给人以直觉上的关联。

HTTP动词

对于资源的具体操作类型，由HTTP动词表示，常用的HTTP动词有下面四个：

• GET（Query）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• DELETE（DELETE）：从服务器删除资源。

举例来说，有一个RESTful API提供学生选课服务，包括老师、学生、课程等信息，则它的路径应该设计成下面这样：

HTTP动作	API	描述
GET	https://api.hbeu.cn/teachers	列出所有教师
GET	https://api.hbeu.cn/students	列出所有学生
GET	https://api.hbeu.cn/courses	列出所有课程
GET	https://api.hbeu.cn/teacher/ID	获取某个指定教师的信息
GET	https://api.hbeu.cn/teacher/ID/students	获取某个指定教师下面的所有学生

使用?用来过滤资源

很多人只是把?简单的当做是参数的传递，很容易造成URI过于复杂、难以理解。可以把?用于对资源的过滤， 例如/teacher/1/students用来表示id为1的教师下面所有的学生，而/teacher/1/students?type=A用来表示该教师下面成绩为A的所有学生， 这种URL通常对应的是一些特定条件的查询结果或算法运算结果。

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&per_page=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?type_id=A：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

API 版本号

1、在URI里边带上版本号
有些API在URI里边带上版本号，例如:

https://api.hbeu.cn/1.0/teachers
https://api.hbeu.cn/1.2/teachers
https://api.hbeu.cn/2.0/teachers

2.将版本号放在HTTP头信息中
如果我们把版本号理解成资源的不同表述形式的话，就应该只是用一个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

两种实现方式各有优劣，大家酌情取舍。

RESTful 框架

Java语言支持RESTful 的框架有：

• Spring MVC
• Jersey
• RESTEasy

总结

REST是一种架构风格，汲取了WWW的成功经验：无状态，以资源为中心，充分利用HTTP协议和URI协议，提供统一的接口定义，使得它作为一种设计Web服务的方法而变得流行。

参考资料

https://zh.wikipedia.org/wiki/REST