深入理解RESTful

通过阅读阮一峰老师的两篇文章,进行笔记的抄录,来加深自己对于 RESTful的理解

深入理解RESTful

RESTful 架构是目前最流行的一种互联网软件架构,它结构清晰、符合标准、易于理解、扩展方便,所以得到越来越多网站的采用。那么,到底什么叫做 RESTful 架构呢?

RESTful 架构

起源

REST这个词,是Roy Thomas Fielding在他2000年的博士论文中提出的。

名称

Fielding将他对互联网软件的架构原则,定名为REST,即Representational State Transfer的缩写。我对这个词组的翻译是”表现层状态转化”。

资源(Resources)

REST的名称”表现层状态转化”中,省略了主语。”表现层”其实指的是”资源”(Resources)的”表现层”。

所谓的“资源”,就是网络上的一个实体,或者说是网络上的一个具体信息,它可以是一段文本、一张图片,一首歌,一种服务,总之就是一个具体的存在。可以用一个 URI (统一资源定位符)指向它,每种资源对应一个特定的 URI ,要获取这个资源,访问它的 URI 就可以,因而 URI 就成了每一个资源的地址或者收拾独一无二的识别符。

表现层(Representation)

“资源”是一种消息实体,可以有多种外在表现形式,把“资源”具体呈现出来的形式,叫做它的“表现层”

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

URI 只代表资源的实体,不代表它的形式,严格地说,有些网站最后的“.html”后缀名是不必要的,因为这个后缀名表示格式,属于“表现层”的范畴,而 URI 应该只代表“资源”的位置。它的具体表现形式,应该在 HTTP 请求的头部信息中用 Accept 和 Content-Type 字段来指定,这两个字段才是对“表现层”的描述。

状态转化(state Transfer)

访问一个网站,就代表了客户端和服务器的一个互动的过程,在这个过程中,就会涉及到数据和状态的变化。

互联网通信协议 HTTP 协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端,因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生“状态转化(State Transfer)” 。而这种转化是建立在表现层之上的,所以就是“表现层状态转化”

客户端用到的手段,只能是 HTTP 协议,具体来说,就是 HTTP 协议里面,四个表示操作的动词: GET/POST/PUT/DELETE。它们分别对应四种基本操作:获取/新建(更新)/更新/删除 资源

综述

RESTful 就是

  1. 每一个 URI 代表一个资源
  2. 客户端与服务器之间,传递这种资源的某种表现层
  3. 客户端通过四个 HTTP 动词,对服务端资源进行操作,实现”表现层状态转化“

误区

RESTful 架构有一些典型的设计误区

最常见的设计误区,就是 URI 中包含动词。因为“资源”是一种实体,所以应该是名称,URI 不应该有动词,动词应该放在 HTTP 协议中。

例子:

URI: /posts/show/1

其中 show 是动词,这个 URI 设计就错误了,正确的应该是

URI: /posts/1

然后用 GET 表示 show

如果某些动作是HTTP动词表示不了的,你就应该把动作做成一种资源。比如网上汇款,从账户1向账户2汇款500元,错误的URI是:

1
POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction,资源不能是动词,但是可以是一种服务:

1
2
3
POST /transaction HTTP/1.1
Host: 127.0.0.1
from=1&to=2&amount=500.00

另一个设计误区,就是在URI中加入版本号

  http://www.example.com/app/1.0/foo

  http://www.example.com/app/1.1/foo

  http://www.example.com/app/2.0/foo

因为不同的版本,可以理解成同一种资源的不同表现形式,所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分(参见Versioning REST Services):

  Accept: vnd.example-com.foo+json; version=1.0

  Accept: vnd.example-com.foo+json; version=1.1

  Accept: vnd.example-com.foo+json; version=2.0

RESTful API 最佳实践

URI 设计

动词 + 宾语

RESTful 的 核心思想就是,客户端发出的数据操作指令都是 “动词+宾语”的结构,比如

GET/articles这个命令,GET是动词,/articles是宾语

动词通常就是五种 HTTP 方法,对应 CRUD(Create增加|Retrieve读取查询|Update更新|Delete删除) 操作

  • GET :读取(Read)
  • POST:新建(Create)
  • PUT:更新(Update)
  • PATCH:更新(Update),通常是部分更新
  • DELETE:删除(Delete)

根据 HTTP 规范,动词一律大写。

动词的覆盖

有些客户端只能使用 GETPOST这两种方法,服务器必须接受 POST模拟其他三个方法(PUTPATCHDELETE

这时客户端发出的 HTTP 请求,要加上 X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖 POST方法

1
2
POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT

上面代码中,X-HTTP-Method-Override指定本次请求的方法是PUT,而不是POST

宾语必须是名词

宾语就是 API 的URI ,是 HTTP 动词作用的对象,它应该是名词,不能是动词,比如 /articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的

  • /getAllCars
  • /createNewCar
  • /deleteAllRedCars

复数 URL

既然 URL 是名词,那么应该使用复数,还是单数?

这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。

为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2

避免多级 URL

常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。

1
GET /authors/12/categories/2

这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。

更好的做法是,除了第一级,其他级别都用查询字符串表达。

1
GET /authors/12?categories=2

下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。

1
GET /articles/published

查询字符串的写法明显更好。

1
GET /articles?published=true

状态码

状态码必须精确

客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数,分成五个类别。

  • 1xx:相关信息
  • 2xx:操作成功
  • 3xx:重定向
  • 4xx:客户端错误
  • 5xx:服务器错误

2xx 状态码

200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

  • GET: 200 OK
  • POST: 201 Created
  • PUT: 200 OK
  • PATCH: 200 OK
  • DELETE: 204 No Content

上面代码中,POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。

此外,202 Accepted状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。下面是一个例子。

1
2
3
4
5
6
7
8
HTTP/1.1 202 Accepted

{
"task": {
"href": "/api/company/job-management/jobs/2130040",
"id": "2130040"
}
}

3xx 状态码

API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。

API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。它与302307的含义一样,也是”暂时重定向”,区别在于302307用于GET请求,而303用于POSTPUTDELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。下面是一个例子。

1
2
HTTP/1.1 303 See Other
Location: /api/orders/12345

4xx 状态码

4xx状态码表示客户端错误,主要有下面几种。

400 Bad Request:服务器不理解客户端的请求,未做任何处理。

401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。

403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。

404 Not Found:所请求的资源不存在,或不可用。

405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。

410 Gone:所请求的资源已从这个地址转移,不再可用。

415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。

422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。

429 Too Many Requests:客户端的请求次数超过限额。

5xx 状态码

5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。

503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

服务器回应

不要返回纯本文

API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json

客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

1
2
GET /orders/2 HTTP/1.1
Accept: application/json

发生错误时,不要返回 200 状态码

有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。

1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json

{
"status": "failure",
"data": {
"error": "Expected at least two items in list."
}
}

上面代码中,解析数据体以后,才能得知操作失败。

这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。

1
2
3
4
5
6
7
8
9
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
"error": "Invalid payoad.",
"detail": {
"surname": "This field is required."
}
}

提供链接

API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。

举例来说,GitHub 的 API 都在 api.github.com 这个域名。访问它,就可以得到其他 URL。

1
2
3
4
5
6
7
8
9
{
...
"feeds_url": "https://api.github.com/feeds",
"followers_url": "https://api.github.com/user/followers",
"following_url": "https://api.github.com/user/following{/target}",
"gists_url": "https://api.github.com/gists{/gist_id}",
"hub_url": "https://api.github.com/hub",
...
}

上面的回应中,挑一个 URL 访问,又可以得到别的 URL。对于用户来说,不需要记住 URL 设计,只要从 api.github.com 一步步查找就可以了。

HATEOAS 的格式没有统一规定,上面例子中,GitHub 将它们与其他属性放在一起。更好的做法应该是,将相关链接与其他属性分开。

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200 OK
Content-Type: application/json

{
"status": "In progress",
"links": {[
{ "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
{ "rel":"edit", "method": "put", "href":"/api/status/12345" }
]}
}

想了解更多详情的,可以点击

参考链接

  1. 理解RESTful架构-阮一峰
  2. RESTful API 最佳实践
0%