从罗伊·菲尔丁(Roy Fielding)的《REST API必须是超文本驱动的》第一段开始,很明显他认为他的工作被广泛误解:
“我越来越沮丧了,因为有很多人称任何基于HTTP的接口都是REST API。今天的例子就是SocialSite REST API。那是RPC。它尖叫着RPC。展示出来的耦合度太高了,应该被给予X评级。”
Fielding列出了几个REST API的属性。其中一些似乎与常见做法和SO等其他论坛上的常见建议相违背。例如:
REST API应该不需要任何先前的知识,除了初始URI(书签)和适合预期受众理解的一组标准化媒体类型(即,可能使用该API的任何客户端都能理解)。...
REST API不得定义固定的资源名称或层级结构(客户端和服务器之间的明显耦合)。...
REST API几乎应该在定义用于表示资源和驱动应用程序状态的媒体类型或在定义扩展关系名称和/或现有标准媒体类型的超文本启用标记方面花费所有的描述性精力。...
"超文本"的概念发挥着核心作用——比URI结构或HTTP动词的含义更为重要。其中一个评论中定义了“超文本”的概念:
当我[Fielding]说超文本时,我的意思是指信息和控件的同时呈现,以便信息成为用户(或自动机)通过获取选择和选择操作的权利。超媒体仅是将文本的含义扩展到包括媒体流中的时间锚点;大多数研究人员已经放弃了这种区别。
超文本并不需要在浏览器上使用HTML。机器可以在他们理解数据格式和关系类型时跟随链接。
我猜这时候,前两点似乎表明像下面这样的Foo资源的API文档会导致客户端和服务器之间的紧密耦合,并且在RESTful系统中没有位置。
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
相反,代理应该被迫通过例如针对/foos发出GET请求来发现所有Foos的URI。(这些URI可能会遵循上面的模式,但这不是重点。)响应使用能够传达如何访问每个项以及可以执行什么操作的媒体类型,从而引起上述第三点。因此,API文档应专注于解释如何解释响应中包含的超文本。
此外,每次请求Foo资源的URI时,响应都包含了代理发现如何继续的所有信息,例如通过它们的URI访问相关和父资源,或在创建/删除资源后采取行动。
整个系统的关键在于响应包含在媒体类型中的超文本本身传达了代理继续的选项。这与浏览器为人类工作的方式类似。
但这只是我此刻的最佳猜测。
Fielding发布了一篇后续文章,回应了他的讨论过于抽象、缺乏示例和术语过多的批评:
那么,对于具有实际思维的REST专家来说,有两个简单的问题:您如何解释Fielding所说的内容,并在记录/实现REST API时如何将其付诸实践?
编辑:这个问题是一个例子,说明如果您不知道自己正在谈论的内容的名称,学习起来会有多困难。在这种情况下,名称为“超媒体作为应用程序状态引擎”(HATEOAS)。