REST API必须是超文本驱动的

http://www.infoq.com/cn/news/2008/12/restapi-must-be-hypertext-driven
Fielding博士的那篇经典论文（中文版）对万维网架构的贡献可谓是居功至伟。可想而知，当REST一词变得流行起来之后，其滥用甚至是“挂羊头卖狗肉”的现象是不可避免的。而糟糕的是，对于那些没有时间、也没有耐心去仔细阅读该论文的人来说，可能就会在看过或用过某些号称具有REST风格的应用之后对REST本身产生错误的理解，进而在错误的思想指导之下错误地运用REST。这正是其创造者本身所不愿意看到的。

这不，Fielding博士本人终于按捺不住发飚了。在其10月28日发表的博文《REST API必须是超文本驱动的》中，博士坦言了他的失望，并对SocialSite REST API提出了批评。同时他还指出，除非应用状态引擎是超文本驱动的，否则它就不是RESTful或REST API。据此，他给出了REST API应该具备的条件：

REST API不应该依赖于任何通信协议，尽管要成功映射到某个协议可能会依赖于元数据的可用性、所选的方法等。
REST API不应该包含对通信协议的任何改动，除非是补充或确定标准协议中未规定的部分。
REST API应该将大部分的描述工作放在定义用于表示资源和驱动应用状态的媒体类型上，或定义现有标准媒体类型的扩展关系名和（或）支持超文本的标记。
REST API绝不应该定义一个固定的资源名或层次结构（客户端和服务器之间的明显耦合）。
REST API永远也不应该有那些会影响客户端的“类型化”资源。
REST API不应该要求有先验知识（prior knowledge），除了初始URI（书签）和适合目标用户的一组标准化的媒体类型（即，它能被任何潜在使用该API的客户端理解）。
按照Fielding博士这些条件，一大批我们熟知的、号称是RESTful的应用和架构无疑都不属于REST的行列，包括Google/Amazon/Yahoo!等大公司所提供的API和应用。可想而知，该文发表之后的反响是巨大的，其后长长的回复列表即是明证。面对诸多疑问，Fielding博士一一做了回复。其言论整理如下：

对于“超文本”，Fielding说道：“我所说的超文本指的是信息与控件的同时呈现，这样一来，信息便具有自解释性（affordance），从而用户（或程序）可以通过它获取选项、并作出选择。”（回复#3）
他认为“真正的RESTful API”就想超文本一样，信息的每个寻址单元显式地（如，link和id属性）或隐式地（如，由媒体类型定义和表示结构推导而来）携带一个地址。（回复#5）鉴于超文本中已经包含了寻址信息，故而他认为接口并不一定需要是可发现的。（回复#11）
对“为什么会有如此多的人对REST理解有误”之一问题，Fielding承认由于他时间的关系对媒体类型的设计未在论文中做详细阐述，但同时强调这并非表示他认为这些内容不重要。（#8）
对于资源建模的目的，Fielding表示这是为了找出哪些资源值得标识、表示和操作。（回复#11）
对于先验知识，Fielding认为客户端是允许有先验知识的，但REST强调的是这些先验知识应该以一种标准化的形式出现。（回复#20）
对于批操作，Fielding认为人们觉得需要批操作是因为他们没有理解资源的范围。他指出资源并非存储项（至少不等同于后台中某些存储项），并且同一资源状态可以由多个资源来分担。如果谁发现他需要一个批操作，那么很可能只是因为他没有定义足够的资源。（回复#21）
不要混淆了应用状态和资源状态，前者指的是计算某个任务的用户应用的状态，后者则是指作为某个服务所暴露出的状态（回复#22）
媒体类型标识出了定义如何处理表示的规范。一旦表示以携带了类型化关系的超文本形式被提供，那么自动化的代理就能像人一样在这些应用之间穿梭自如。（回复#30）
对于安全性的问题，Fielding说道：“RESTful系统实现安全操作的方式和其他任何消息传递协议的方式是一样的：不是封装消息流（SSL、TLS、SSH、IPspec……），就是加密消息（PGP、S/MIME等）。”（回复#34）
在这样短的一篇新闻中很难详细的罗列该文所有的内容和评论，尤其是其间不乏某些很有价值的讨论和观点。请一定要阅读一下Fielding博士的这篇引起广泛讨论的文章。另外，REST论文中文版的译者之一dlee也在JavaEye论坛上就此文发起了讨论。其中他这样写道：

Fielding发表这篇blog，这件事情其实并不出我的意外。我在两年前就很奇怪世界上为何一下子冒出来这么多REST专家。那一年，我翻译了《Ajax Patterns and Best Practices》。这本书的内容非常深入，作者Christian Gross宣称他所设计的所有模式遵循的都是REST架构风格。但是Gross先生却没有将REST的来龙去脉讲清楚，甚至只字未提Fielding的那本著名的博士论文。

REST似乎是一个技术界的罗生门，每个人的描述都不一样，而他们都坚信自己的理解才是正确的。……

现在真相大白了，Fielding对于REST架构风格定下了如此严格的判断标准，世界一下子清静了。
附注：非常感谢《RESTful Web Service中文版》的译者徐涵对本文提出的意见和帮助。
http://www.haogongju.net/art/239055
原文：
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
我是越来越失望了，许多人把任何基于HTTP的接口叫做REST API，眼前的例子就是SocialSite REST API。那是RPC，实实在在的RPC。它与显示如此耦合，再差也莫过于此

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
基于超文本概念，如何才能确保清晰的REST架构风格呢？这样来说吧，如果应用程序状态引擎（即API）不是由超文本驱动的，那就不是RESTful也不是REST的API。就这么简单。某些REST方面的破手册是否该修正一下呢？

API designers, please note the following rules before calling your creation a REST API:
API的设计者们，把你们的那些东西叫做REST API前请注意以下的规则：

A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that identification. [Failure here implies that identification is not separated from interaction.]
REST API不应依赖于任何特定的通讯协议，在采用某个具体协议时可能受限于元数据的有效性、方法的选择等。通常，协议元素使用URI作标识时，对该标识必须允许运用任何URI方案。[ 不符合这一点意味着标识与交互没有分离 ]
A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete. [Failure here implies that the resource interfaces are object-specific, not generic.]
REST API不应修改通讯协议中预留出来作为补充或修正标准协议用途的资源，例如HTTP的PATCH方法和Link head域。违背了这一原则的方案应当单独定义，或者至少在附录中标注出来这样的方案最终会废弃掉。[ 不符合这一点意味着资源接口是对象相关的，不通用 ]

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
REST API应当将绝大部分精力放在媒体类型的定义上，或者是扩展关系名称的定义、已有超文本标记中的标准媒体类型等方面，以实现资源的表述、操作应用程序状态。任何类似于对某某URI应当使用什么样的方法等工作，都应当完全定义在特定媒体类型的处理规则范围中（绝大部分情况下已有媒体类型都已经定义好了这些规则）。[ 不符合这一点意味着交互是由其它信息驱动，而不是超文本 ]

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
REST API决不能定义固定的资源名称或者层次关系（这是明显的客户端、服务器端耦合），服务器必须可以自由控制自己的名称空间。应当像HTML forms和URI模板一样，通过媒体类型和链接关系指示客户端如何构造正确的URI。[ 不符合这一点意味着客户端在通过其它信息（例如领域相关标准）猜测资源结构，这是数据导向，类似于RPC的函数耦合 ]

A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto]
REST API决不能使用对客户端有重要意义的类型化资源。规范的作者可能使用资源类型描述接口背后的服务器端实现，但这些类型必须与客户端无关，对客户端不可见。对客户端唯一有意义的类型是当前的表述性媒体类型和标准的关系名称。[ 同上 ]

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
使用REST API应该只需要知道初始URI（书签）和一系列针对目标用户的标准媒体类型（任何客户端都了解用来操作该媒体类型的API）。这样所有的应用程序状态转换都通过这样的方式进行：服务器在返回的表述性消息中提供选项，由客户端进行选择，或者是伴随着用户对表述性内容的操作而进行。状态转换由客户端对媒体类型的了解程度和资源通讯机制决定，或者受限于这些因素，这些问题都可以根据实际情况得以改善的（例如使用javascript这种code-on-demand技术）。[ 不符合这一点意味着交互是由其它信息驱动，而不是超文本 ]

There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword for your API.
也许还有其它一些规则我一时想不起来了，但在那些所谓的REST API中通常都违背了上面这些超文本约束相关的规则，请纠正这些错误或者改用其它称谓吧