问题标签 [hateoas]

正如每个人可能已经注意到的那样，有很多假的/基本的 REST-API（它们实现了 HTTP-API 并将其称为 REST，而不遵循超文本作为应用程序状态的引擎要求，这导致Roy T. Fielding 著名的咆哮，他是第一个指定 REST 范式的人）。

我一直找不到真正超文本驱动的 REST 实现的任何实际示例，以及用于状态转换的相关应用程序特定媒体类型定义。

是否有此类实现的任何可公开访问的示例？

我认为我对 REST 了解的大部分内容显然是错误的——而且我并不孤单。这个问题的引文很长，但似乎很有必要，因为信息有点分散。如果您已经熟悉该主题，那么实际问题将在最后出现。

从 Roy Fielding 的REST APIs must be hypertext-driven的第一段开始，很明显他认为他的工作被广泛误解了：

我对将任何基于 HTTP 的接口称为 REST API 的人数感到沮丧。今天的例子是SocialSite REST API。那就是RPC。它尖叫 RPC。展示的耦合太多了，应该给它一个 X 评级。

Fielding 继续列出 REST API 的几个属性。其中一些似乎违背了 SO 和其他论坛上的常见做法和常见建议。例如：

• 除了初始 URI（书签）和适合目标受众（即，任何可能使用 API 的客户端都可以理解）的标准化媒体类型集之外，应该在没有任何先验知识的情况下输入 REST API。...

• REST API 不得定义固定的资源名称或层次结构（客户端和服务器的明显耦合）。...

• REST API 应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型，或定义扩展关系名称和/或现有标准媒体类型的超文本启用标记。...

“超文本”的概念起着核心作用——比 URI 结构或 HTTP 动词的含义更重要。“超文本”在评论之一中定义：

当我 [Fielding] 说超文本时，我的意思是信息和控制的同时呈现，使得信息成为用户（或自动机）获得选择和选择动作的可供性。超媒体只是对文本意味着在媒体流中包含时间锚点的扩展；大多数研究人员已经放弃了这种区别。

超文本不需要是浏览器上的 HTML。当机器了解数据格式和关系类型时，它们可以跟踪链接。

我猜到了这一点，但上面的前两点似乎表明 Foo 资源的 API 文档如下所示会导致客户端和服务器之间的紧密耦合，并且在 RESTful 系统中没有位置。

相反，应该强制代理通过例如向 /foos 发出 GET 请求来发现所有 Foos 的 URI。（这些 URI 可能会遵循上面的模式，但这不是重点。）响应使用的媒体类型能够传达如何访问每个项目以及可以用它做什么，从而产生了上面的第三点. 出于这个原因，API 文档应该专注于解释如何解释响应中包含的超文本。

此外，每次请求 Foo 资源的 URI 时，响应都包含代理发现如何继续进行所需的所有信息，例如，通过其 URI 访问关联资源和父资源，或在创建后采取行动/删除资源。

整个系统的关键在于响应由包含在媒体类型中的超文本组成，该媒体类型本身传达给代理选项以进行处理。这与浏览器为人类工作的方式没有什么不同。

但这只是我在这个特定时刻的最佳猜测。

菲尔丁发表了一篇后续文章，回应批评称他的讨论过于抽象、缺乏示例且行话丰富：

其他人会尝试以更直接或更适用于当今某些实际问题的方式来解读我所写的内容。我可能不会，因为我太忙于处理下一个话题、准备会议、编写另一个标准、去某个遥远的地方旅行，或者只是做一些让我觉得我已经赚到了薪水的小事。

因此，对于 REST 专家来说，有两个简单的问题，有实用的思维方式：您如何解释 Fielding 所说的内容，以及在记录/实施 REST API 时如何将其付诸实践？

编辑：这个问题是一个例子，说明如果你没有为你所谈论的内容命名，那么学习一些东西会有多么困难。在这种情况下，名称是“作为应用程序状态引擎的超媒体”（HATEOAS）。

Does anybody know of an implementation of a REST client that embraces the constraint of Hypermedia as the Engine of Application State (HATEOAS)?

The Sun Cloud API seems to be a good candidate, judging from the way it's documented and a statement by the author to the effect that Ruby, Java, and Python implementations were in the works. But so far I've found no trace of the code.

I'm looking for anything - even a partial implementation would be helpful.

据我了解，使用超文本驱动的RESTful Web 服务，客户端不应该知道任何关于服务器 URI 布局的信息，除了几个众所周知的入口点。这应该使服务器能够控制自己的 URI 空间并减少与客户端的耦合。

当服务的客户端成功发送创建新资源的请求时，服务会响应 201 CREATED 并在 Location 标头字段中提供可以访问新资源的 URI。

是否应该允许客户端存储此 URI 以在将来启用对资源的直接访问，如果可以，持续多长时间？如果 URI 被客户端缓存，这似乎设置了一种情况，即每次服务器更改其 URI 布局时，它需要确保在访问旧 URI 时提供永久重定向。否则客户端中断。几年后，这种重定向系统可能会失控。

与使用 URI 模板的 REST-RPC 混合方法相比，这种情况似乎不会给服务器更多对其 URI 空间的控制。

有很多关于缓存表示的信息，但是在超文本驱动的 RESTful 系统中缓存 URI 呢？

I am working on an enterprise system that will utilise a RESTful web service between mobile clients and a central server. As RESTful as possible, let's say.

My question relates to HATEOAS (hypermedia as the engine of application state), and the use of custom xml in HTTP response bodies.

This system will never ever be used by public clients, but I like the HATEOAS idea of being able to modify the server-side resource allocation pattern later without having to reconfigure each of the clients independently. If we decide that due to scaling issues we need to spread the server function over multiple physical boxes, no problem, this will be reflected in the URIs that are generated when a client (or the server under instruction from a client) creates a new resource.

Our business domain is highly specific and unusual. As such, I would like to use custom XML for HTTP response entity bodies throughout the web service, and the client will parse resource URIs out of the xml in order to stay informed of resource locations that it can use when modifying its own application state. I know that this 'breaks' the H part of HATEAOS.

e.g. when a client POSTs a transaction to the server for processing, the server might include the following xml fragment in the 201 HTTP response body (as part of a larger xml document). The server would also inform the client of the URI for the newly created transaction resource itself, but this would probably only be included in the Location HTTP header.

Is this so bad? There is very little chance that the clients using this service will ever be browser based. What are the other advantages of hypermedia over delivering the uris as plain text within xml?

I guess I could go to XHTML, but the parser on our mobile platform is much more efficient with POX.

所以现在我明白了，我们都应该实现我们的 RESTful 服务，提供使客户能够遵循HATEOAS原则的表示。虽然理论上这一切都说得通，但我一直在网上搜索，以找到一个严格遵循这个想法的客户端代码的一个很好的例子。

我读得越多，我就越觉得这是一场学术讨论，因为实际上没有人这样做！人们可以尽情地抱怨 WS-* 堆栈的许多缺陷，但至少很清楚如何编写客户端：您可以解析 WSDL 并生成代码。

现在我明白了，对于一个好的 RESTful 服务来说，这不应该是必需的：你应该只需要了解所涉及的关系和表示，你应该能够动态地对它们做出反应。但即便如此，这个原则现在不应该被提炼和抽象到一些通用库中吗？输入有关您可能收到的表示和关系的信息，并获得一些可以在您的应用程序中使用的更有用的高级代码？

这些只是我的半生不熟的想法，但我只是担心如果我现在潜入并编写一个适当的 RESTful API，实际上没有人能够使用它！或者至少在后面使用它会很痛苦，因为人们将不得不编写胶水代码来解释我提供的关系和表示。

任何人都可以从客户的角度对此有所了解吗？有人可以展示一个正确动态/反应式 RESTful 客户端代码的示例，以便我了解我实际为之写作的受众吗？（最好还是一个提供一些抽象的客户端 API 的例子）否则它都是非常理论的......

[编辑：注意，我在这里发现了一个类似的问题，我认为没有得到真正的回答，作者被维基百科存根骗了！]

在使用 HATEOAS 设计 RESTful Web 服务时，将链接显示为完整 URL（“ http://server:port/application/customers/1234 ”）与仅显示路径（“/application/客户/1234")?

这个问题有点长，请多多包涵。在 REST 中，我认为我们不应该需要 WADL 或任何 IDL。而是隐含地涵盖其概念的东西。我的想法是当我们（人类）上网时，当我们第一次访问一个网站时，我们不知道它提供什么服务。你发现那些在 html 主页（或帮助部分中的站点地图页面）上的那些，或者可能只是主页上的主菜单。如果你打个比方，主页或站点地图对我们人类来说就像 WSDL 对 WS-* 或 WADL 对 REST 服务一样。只是它就像任何其他 html 内容一样。我认为在 REST 中，以下是做事的好方法，尊重 HATEOS 范式。拥有一个顶级（或默认）资源，其中列出了指向您的其他资源的链接。对于图书馆的例子，说 RestLibrary.com/ 它可能是这样的：

请注意，假定媒体类型“application/vnd.libraryml+xml”是定义的标准或（可能只是专有词汇）名为 libraryml。此外，客户端应该能够理解这个“主页”资源（元素根、资源和链接）。这是可以用来代替 WADL 的部分：任何客户都应该可以理解的抽象词汇表。例如，您可以使用像 Atom 这样的现有标准。但主要思想是要有一个任何客户都能理解的抽象词汇。那为什么不用WADL呢？wadl 仅用于服务发现。这里的想法是拥有一个轻量级的抽象词汇，作为超媒体的基础。一个“根”词汇。就像在 owl 中一样，我们有 owl:thing...etc 现在如果客户端知道“libraryml” 标准它可以跟随链接到它理解的东西（在解析媒体类型属性和 xmlns 之后）。如果没有，那就不会了。

当我无法理解如何处理 REST 架构中的某些内容时，我倾向于了解我们人类如何在 Web 中进行处理。在 Web 中，我们拥有 HTML 的通用语言，它使站点构建者能够交付任何特定内容，而不管其对客户端（用户）的含义如何，浏览器理解 HTML，但不理解其内容的“含义”。理解（特定领域）内容的是用户。如果我去说 QuantumPhysics.org，我的浏览器可以呈现主页（毕竟它只是 html），我可以阅读主页。如果我了解量子，那么我可以继续浏览。如果我不这样做，我就出去（除非我想学习硬路:)）

• 在 RetsLibrary.com 示例中，客户端应用程序就像我 + 我的浏览器一样
• 在 QuantumPhysics.org 上。媒体类型“application/vnd.libraryml+xml”是量子物理学（知识）。
• http 在这两个示例中都是 http。
• 现在 QuantumPhysics.org 的 HTML 在 RestLibrary.com 是 XML + 那个小小的抽象词汇（根资源和链接，你可以用 Atom 之类的东西代替）。

那么这种方法有什么价值吗？难道我们不需要一个根微型超词汇表，这样我们就可以通过超媒体和“初始 URI”概念取得成功吗？

编辑 是啊，为什么不将 RDF 作为根词汇！

据说，在一个定义良好的 RESTful 系统中，客户端只需要知道根 URI 或少数几个众所周知的 URI，客户端将通过这些初始 URI 发现所有其他链接。我确实理解这种方法的好处（解耦客户端），但对我来说缺点是客户端每次尝试访问某些东西时都需要发现链接，即给定以下资源层次结构：

如果我们遵循“客户端只需要知道根 URI ”的方法，那么客户端应该只知道根 URI，即上面的 /collection1，其余的 URI 应该由客户端通过超媒体链接发现。我发现这很麻烦，因为每次客户端需要执行 GET 时，例如在 sub1sub1sub1sub1 上，客户端是否应该首先在 /collection1 上执行 GET 并在返回的表示中定义以下链接，然后对子资源执行更多 GET 以到达想要的资源？还是我对连通性的理解完全错误？

最好的问候， 苏雷什

HATEOAS（作为应用程序状态引擎的超媒体）建议是否暗示查询字符串不是 RESTful？

编辑：下面建议查询字符串可能与状态没有太大关系，因此这个问题令人费解。我建议除非客户端填写参数，否则 URI 具有查询字符串是没有意义的。如果客户端正在填写参数，那么它就是在掺假服务器提供的 URI，我想知道这是否违反了 RESTful 原则。

编辑 2：我意识到如果客户端将其视为不透明的查询字符串似乎是无害的（并且查询字符串可能是遗留的，因此很方便）。但是，在下面的答案之一中，引用了 Roy Fielding 的话说，应该将 URI 视为透明的。如果它是透明的，那么我认为鼓励掺假，这似乎淡化了 HATEOAS 原则。这种稀释是否仍然与 HATEOAS 一致？这就提出了一个问题，即 REST 是否需要像 URI 构建那样紧密耦合。

更新在这个 REST 教程http://rest.elkstein.org/建议 URI 构建是糟糕的设计并且不是 RESTful。它还迭代了@zoul 在接受的答案中所说的内容。

例如，“产品列表”请求可以返回每个产品的 ID，并且规范说您应该使用http://www.acme.com/product/PRODUCT_ID来获取更多详细信息。那是糟糕的设计。相反，响应应该包含每个项目的实际 URL：http://www.acme.com/product/001263等。是的，这意味着输出更大。但这也意味着您可以根据需要轻松地将客户引导到新的 URL

如果一个人正在查看此列表并且不想要他/她可以看到的内容，则可能会有一个“前 10 个项目”和一个“下一个 10 个项目”按钮，但是，如果没有人，而是一个客户端程序, REST 的这一方面似乎有点奇怪，因为客户端程序可能没有使用所有“ http://www ”。