如果它们应该使用HATEOAS,为什么要记录RESTful API？

Question

为了掌握RESTfulAPI 的基本目的,我开始深入研究HATEOAS.

根据那个维基百科页面,

除了对超媒体的一般理解之外,REST客户端不需要有关如何与任何特定应用程序或服务器交互的先验知识.相比之下,在面向服务的体系结构(SOA)中,客户端和服务器通过文档或接口描述语言(IDL)共享的固定接口进行交互.

现在,我并不真正理解它应该如何工作,除非事先知道API中可用的内容,否则它会谴责其声明的目的HATEOAS.事实上,Swagger等工具的存在是为了记录RESTfulAPI 的明确目的.

因此,虽然我明白HATEOAS可以允许web服务指示资源的状态,但我错过了链接(haha),它展示了客户端应用程序如何在没有某种类型的情况下找出如何处理返回的后续链接"固定接口".

HATEOAS应该如何实现这一目标？

Answer 1

你是混乱的事情.像Swagger这样的工具不存在用于记录RESTful API的明确目的.它们的存在是为了记录非RESTful的HTTP API!对于非超文本驱动的API,您需要这样的工具,并且需要关注URI语义和方法而不是媒体类型的文档.所有那些生成URI和HTTP方法列表的花哨工具都与您在REST中应该做的完全相反.引用Roy Fielding关于此事:

REST API应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型,或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记.在媒体类型的处理规则的范围内(并且在大多数情况下,已经由现有媒体类型定义)应该完全定义用于描述在感兴趣的URI上使用什么方法的任何努力.[失败在这里意味着带外信息驱动交互而不是超文本.]

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

HATEOAS不排除对所有文档的需求.HATEOAS允许您将文档集中在媒体类型上.您的应用程序应该符合底层协议 - 大部分时间都是HTTP - 并且该协议的权威文档是您的客户驱动交互所需的全部内容.但他们仍然需要知道他们正在与之互动.

例如,当您输入Stack Overflow时,您知道有用户,问题和答案.您需要有关这些内容的文档,但是您不需要详细说明链接或按钮上的单击操作的文档.您的浏览器已经知道如何驱动它,这就是它在其他地方的工作方式.

引用另一个答案,REST是Web本身的架构风格.当您输入Stack Overflow时,您知道用户,问题和答案是什么,您知道媒体类型,并且网站为您提供了指向它们的链接.REST API必须执行相同的操作.如果我们按照人们认为应该完成REST的方式设计Web,而不是让主页上有问题和答案的链接,我们会有一个静态文档解释为了查看问题,你必须采用URI stackoverflow .com/questions /,用Question.id替换id并将其粘贴到您的浏览器上.这是无稽之谈,但这就是许多人认为REST的含义.