本文描述了识别一个接口是否真的是 RESTful 接口的基本方法。符合 REST 架构风格的接口,称为 RESTful 接口。本文不打算从架构风格的推导方面描述,而是从 HTTP 标准的方面描述。识别的方法同时也是指导实践的原则。
一、是否使用了正确(合适)的方法
目前对于 HTTP 标准滥用较多的,就是方法。谈起 RESTful 接口的方法,很多资料告诉大家,说 GET、POST、PUT、DELETE,分别对应数据库操作的 SELECT、INSERT、UPDATE、DELETE。其实这种理解是不正确的。
方法有两个性质:安全性与幂等性;以及一个语义:动作本身的意思。RESTful 接口为各种数据抽象为资源,对资源的操作,主要是依据方法的两个性质,其次才是语义。
GET 方法的语义是获取资源,性质是安全、幂等。也就是说,对资源进行安全幂等的操作,应该用 GET 或 HEAD,当目的是获取资源时,选用 GET,目的是获取资源的元数据时,使用 HEAD。使用安全幂等的方法执行不安全或不幂等的操作,都是错误的。一个典型的例子是:
1 GET /book/357?op=delete
这个例子的意图是删除 ID 为 357 的 book,DELETE 是不安全的操作,却使用了 GET 这个安全幂等的操作。这作法的副作用是可能被缓存,所有组件(包括搜索引擎)都认为它是安全的,从而可能不加任何限制地对它进行访问。
POST 方法的语义是提交资源。“提交”本身就是一个比较抽象的动词,即它的语义是可以根据环境变化的,如果将它与 INSERT 对应起来,是以偏概全的。它的性质是不安全、不幂等。这意味着所有组件对它都不缓存,不重复发送请求。执行不安全、不幂等的操作,唯有选择 POST 方法(标准未规定的所有自定义方法,在性质上等同于 POST)。
一个不安全、不幂等的方法,可以执行安全、幂等的操作,前提是需要牺牲缓存等属性。比如提交一个很多参数的查询,可以使用 POST。
HTTP/1.1标准那么多年,HTML标准到5了,为什么HTML的 form 只有 GET 和 POST 两种 action ?为没有不把 PUT、DELETE、PATCH 等方法加进去?其实是有原因的。
首先,form 元素的提交表单的按钮是 submit,与 POST 的语义是等同的。
其次,当浏览器获得一个资源时,form 只是资源的一部分,不能表示整个资源,根据 PUT/DELETE/PATCH 的定义,它无法表示它们。
由于 POST 的性质与抽象的语义,在没有合适的方法时,都可以使用 POST 代替。因此,将 POST 等同于新增/插入的那些文章或教材,都在误导人。
篇幅有限,其它方法不说了,网上基于其它方法的文章基本正确的。
二、是否支使媒体协商
媒体协商是指客户端和服务器对某种媒体类型的处理能力。一般情况下,客户端并不知道服务器能处理哪种媒体。浏览器就是典型代表,它在无先验知识的情况下,会进行媒体探测:
1 GET / HTTP/1.1
2
3 Host: example.com
4
5 Accept: text/html; q=1.0, image/*; q=0.8, */*; q=0.1
这是告诉服务器,我能非常有效地处理 HTML 类型的资源,图片也是很有效的,其它的资源类型,我也能接受。于是服务器就优先按 HTML 返回资源,如果没有 HTML 或 Image,就返回服务器自身最合适的,如 application/json。
假设服务器仅支持 application/json,当客户端要求一个 application/xml 时,应当返回 415 Unsupported Media Type,并在正文中说明支持哪种媒体类型。
举个值得学习的案例,Github:https://api.github.com/ ,大家可以自己试试。
三、是否能够进行状态转移
这一点非常重要,也是 REST 的本意,状态转移!HTTP 标准实现的 REST 中,连接(Link)是实现状态转移的重要组件(HTML 的超链接和表单也是)。
在无先验知识的前提下,客户端请求资源 / ,这个资源及其元数据,要能够为应用程序的下一个状态的转移提供必要的连接。有时候甚至要提供文档说明的连接。
例如,当我们访问 https://api.github.com/ 时,我们看到一个连接的列表。通过这些连接,我们的客户端就可以跳转到另一个状态,从而实现整个应用程序的状态转移。状态如何更好的转移(甚至是自动化的状态转移),就要依赖于连接的关系(rel)以及连接的媒体类型(type)和可选的文档。
这种状态转移的能力,正是 REST 的魅力。诚然,最成功的 REST 客户端是浏览器,最成功的媒体类型是 text/html,最成功的 REST 是 HTTP,通过 URI 标准构建的连接,进化成我们今天无法量化的巨大的分布式系统:Web。
额外一点,一个 RESTful 的接口是不需在路径或头部字段中使用接口的版本号的。RESTful 接口这种说法,也有误。REST有统一接口的概念,但这个概念一般是指 HTTP 标准。在一个 RESTful 的环境中,一切事物都是资源,资源是没有版本号的。版本号是 API 的概念,API 是 RPC 的事物。
资源一旦发布,其结构就基本上不再发生变化。唯一能够变化的资源结构是在对旧资源无副作用的前提下,新增资源的字段或属性。当新增或删除的属性与当前资源的结构不兼容时,则需要增加一个或一类新的资源。因此,在 RESTful 实践中,是不需要使用版本号来标识资源的。
当然,RESTful 内容的丰富,远远不止以上所提到的三点。但这三点是非常基本的要求。