REST HATEOAS - 客户端如何知道链接语义？

Question

假设我有一个完全实现的REST API，同时也提供HATEOAS。假设我浏览根目录，除了自关联外，还返回另外两个链接 (例如一个用于 /users 和一个用于 /orders)。据我所知，HATEOAS 可以消除带外信息的需求。那么客户端如何知道 users 是什么意思呢？语义存储在哪里？

我知道这可能是一个愚蠢的问题，但我真的想知道。

- user3820870

---

客户端应该如何知道“用户”是什么意思？这是一个非常好的问题。在我看来，整个HATEOAS概念都无法回答这个问题。语义无法通过带内传输进行传递。那么带内链接的好处在哪里呢？ - user1907906

我同意。"皇帝"没有穿内裤。 - John Saunders

感谢您的贡献！ :) - user3820870

这不是一个愚蠢的问题。这是许多人方便地忽略的事情。 - pinkpanther

Answer 1

假设您刚刚发现Twitter，并首次使用它。在您的Web浏览器中，您会看到一列段落，页面上散布着许多链接。您知道有一种方法可以做些什么，但您不知道具体可用的操作。您该如何找出它们呢？

好吧，您查看链接并考虑它们的名称意味着什么。一些您根据惯例立即识别出来：作为经验丰富的Web用户，您对单击“主页”、“搜索”和“退出登录”链接所要完成的工作有相当好的了解。

但其他链接具有您不认识的名称。"转推"是什么意思？那个小星星图标是做什么的？

基本上，您或任何人都有两种方法找出这个问题：

1. 通过实验，也就是点击链接并观察结果，然后从结果中推断每个链接的含义。

2. 通过某些带外信息来源，例如在线帮助、通过Google搜索找到的教程或坐在你旁边的朋友解释该网站如何工作。

REST API也是一样的。(回想一下，REST旨在模拟Web与人类互动的方式。)

虽然原则上计算机(或API客户端开发人员)可以通过实验推断链接关系的语义，但显然这是不切实际的。那么只剩下

1. 约定，基于例如IANA的标准化链接关系列表和它们的含义。

2. 带外信息来源，例如API文档。

REST要求客户端开发人员依赖于API本身之外的东西来理解链接关系的含义并不矛盾。这是人类使用网站的标准做法，而人类使用网站就是REST的模型。

REST所实现的是消除与API交互的机制方面需要的带外信息的需求。回到Twitter的例子，您可能需要有人在某个时候向您解释“retweet”链接的确切含义。但是，您不需要知道要键入的特定URL，或要执行操作的推文的ID号码，甚至不需要知道推文具有唯一的ID号码。Web的设计意味着一旦您找出要单击的链接，所有这些复杂性都为您处理。

因此，REST API也是如此。虽然在大多数情况下，计算机或程序员只需要被告知每个链接关系的含义。但是一旦他们获得了这些信息，他们就可以在不需要了解有关其所有组成细节的任何其他信息的情况下浏览整个API。

- user473305

---

非常感谢您的详细解释！基本上，这就是让客户端独立于API更改的全部内容，对吗？假设我浏览根目录并返回一个包含以下内容的JSON： {"links":[ { "orders" : "http://someIP/orders" }]} 然后客户端“知道”（因为我必须以某种方式让客户端了解“订单”一词的语义），它可以在该链接处找到资源。如果链接更改，则仍然能够找到订单。 希望我已经以可理解的方式写出了这篇文章 :) - user3820870

是的，没错。Twitter的类比在这里同样适用：Twitter实际上在过去一年左右进行了重大的网站重构，将许多实现从客户端移回服务器，并更改了许多站点的URL。但由于Web只需要您知道“转推”等操作的含义而不需要了解其机制，因此每个人都能够继续像什么也没有发生一样使用该站点。 - user473305

我应该清楚地表达：据我所知，REST 不会将客户端免受 API 实现变更的影响作为一种特定的设计目标，但采用 HATEOAS 为 API 提供了一种非常有用的结果，即保护客户端免受变更的影响。 - user473305

好的 - 非常感谢您的快速帮助！ :) - user3820870

Answer 2

REST不能消除对带外信息的需求。您仍然需要记录媒体类型。REST消除了客户端与API底层协议交互中的带外信息需求。

语义由媒体类型记录。您的API根是一个媒体类型资源，比如说application/vnd.mycompany.dashboard.v1+json，该媒体类型的文档将解释链接关系users指向与当前认证用户相关的application/vnd.mycompany.user.v1+json集合，而orders则指向application/vnd.mycompany.order.v1+json集合。

这里可以用图书馆类比。当您进入一家图书馆寻找一本书时，您知道如何阅读一本书，知道如何走到书架上并拿起书，并知道如何向图书管理员寻求方向。每个图书馆可能有不同的布局和书架组织方式，但只要您知道要找什么，您和图书管理员使用相同的语言，就能找到它。然而，期望图书管理员教您什么是书是不现实的。

- Pedro Werneck