rest - 如果应该使用 HATEOAS，为什么要记录 RESTful API？

Question

努力掌握 RESTful 的根本目的API，我已经开始深入研究 HATEOAS .

根据那个维基百科页面，

A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in a service-oriented architecture (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).

现在，我真的不明白它应该如何工作，除非事先知道 API 中可用的内容，这否定了 HATEOAS 的既定目的。 .事实上，Swagger 等工具存在的目的是为了记录 RESTful蜜蜂。

所以虽然我理解 HATEOAS可以允许 web 服务指示资源的状态，我错过了链接(哈哈)演示客户端应用程序如何在没有某种“固定接口(interface)”的情况下弄清楚如何处理返回的后续链接.
HATEOAS怎么样应该做到这一点？

Answer 1

你把事情弄糊涂了。像 Swagger 这样的工具并不存在用于记录 RESTful API 的明确目的。它们的存在是为了记录非 RESTful 的 HTTP API!对于非超文本驱动的 API，您需要类似的工具，并将文档重点放在 URI 语义和方法上，而不是媒体类型。所有那些生成 URI 列表和 HTTP 方法的花哨的工具与你在 REST 中应该做的完全相反。在这个问题上引用罗伊菲尔丁的话:

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.]

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

HATEOAS 并不排除对所有文档的需求。 HATEOAS 允许您将文档集中在您的媒体类型上。您的应用程序应该符合底层协议(protocol)——大多数时候是 HTTP——并且关于该协议(protocol)的权威文档是您的客户端应该需要的所有 开车互动。但他们仍然需要知道他们正在与什么互动。

例如，当您进入 Stack Overflow 时，您就知道有用户、问题和答案。您需要有关这些东西究竟是什么的文档，但您不需要详细说明单击链接或按钮的作用的文档。您的浏览器已经知道如何驱动它，这就是它在其他任何地方的工作方式。

报价 another answer , REST 是 web 本身的架构风格。当您进入 Stack Overflow 时，您就会知道用户、问题和答案是什么，您知道媒体类型，并且网站会为您提供指向它们的链接。 REST API 也必须这样做。如果我们按照人们认为 REST 应该完成的方式设计 Web，而不是有一个带有问题和答案链接的主页，我们会有一个静态文档说明为了查看问题，您必须使用 URI stackoverflow .com/questions/，将 id 替换为 Question.id 并将其粘贴到浏览器上。这是胡说八道，但这就是许多人认为的 REST。