rest - 如何记录 API 并仍然尊重 HATEOAS？

Question

关闭。这个问题不满足Stack Overflow guidelines .它目前不接受答案。












想改善这个问题吗？更新问题，使其成为 on-topic对于堆栈溢出。

3年前关闭。




Improve this question




我正在通过 Http 设计一个类似于 REST 的 API。

我需要 API 客户端(应用程序，而不是浏览器)到 按照链接 ( HATEOAS )，而不是构建它们。
此外，出于某些原因，我仍然会使用可读的 URL that can be disagreed .
但是，如果存在记录 url 模板的漂亮方法( like these ones )，我认为这不是正确的方法，因为它显然会诱使合法的开发人员自己构建 url。

那么，如何以尊重 HATEOAS 的方式记录 API？

我们经常发现 Discoverability 与 HATEOAS 相关.. 老实说，我认为这在现实生活中还不够:商业概念多种多样，难以理解，客户开发人员不是你的队友..
有意义的名字显然是不够的。

开发人员需要使他们的客户端应用程序..

导航 从入口url进入API到相关文档

构建有效的请求(参数和主体)和 翻译 在语义上没有歧义的响应。

那么，如何记录这个？

是否有以这种方式生成文档的现有工具？

“词汇表”是否足以填补可发现性和明确解释之间的差距？

也许 API 的 html 表示(Accept:text/html)可以返回人类可读的文档...

..对此有任何其他想法或经验吗？

相关概念:
Design with Intent , 版本控制, Level 3 API

Answer 1

首先，可读的 URI 没有任何问题，用户可以通过手动构建 URI 轻松探索您的 API。只要他们不使用它来驱动实际的 API 使用，那根本就不是问题，甚至是 Roy Fielding 本人的鼓励。在 URI 必须是不透明的基础上的分歧是一个神话。在这件事上引用菲尔丁自己的话:

Maybe I am missing something, but since several people have said that REST implies opaqueness in the URI, my guess is that a legend has somehow begun and I need to put it to rest (no pun intended).

REST does not require that a URI be opaque. The only place where the word opaque occurs in my dissertation is where I complain about the opaqueness of cookies. In fact, RESTful applications are, at all times, encouraged to use human-meaningful, hierarchical identifiers in order to maximize the serendipitous use of the information beyond what is anticipated by the original application.

It is still necessary for the server to construct the URIs and for the client to initially discover those URIs via hypertext responses, either in the normal course of creating the resource or by some form of query that results in a hypertext list. However, once that list is provided, people can and do anticipate the names of other/future resources in that name space, just as I would often directly type URIs into the location bar rather than go through some poorly designed interactive multi-page interface for stock charts.

http://osdir.com/ml/web.services.rest/2003-01/msg00074.html

如果您需要您的客户端开发人员跟踪超链接而不是手动构建 URI，根据我的经验，我认为最好的方法是将其作为工作环境中的文化变革进行推广。就我而言，我有一位支持我的经理，所以这要容易得多。您应该警告他们 URI 命名空间受服务器控制，并且 URI 可能随时更改。如果他们的客户因为不遵守而中断，那不是你的责任。举办某种研讨会或演示来解释 HATEOAS 的工作原理以及对每个人的好处也很有帮助。我注意到很多街头 REST 开发人员认为这是多余的，直到他们真正得到它。

现在，为了解决您的主要问题，您不应该记录 API，您应该将您的文档工作重点放在您的媒体类型上。再次引用菲尔丁:

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

这意味着，您应该为您的表示提供自定义媒体类型，而不是记录 API 端点或 URI，您应该记录这些媒体类型和其中可用链接的操作。例如，假设您有一个用于诸如 StackOverflow 之类的问答网站的 API。与其让 API 文档告诉他们他们应该发布到问题表示中的 rel:answers 链接以便与当前用户一起回答问题，您的问题应该具有媒体类型 application/vnd.yourcompany.question+xml并且在该媒体类型的文档中，您说对 rel:answers http 链接的 POST 将回答该问题。

我不知道任何现有的工具，但根据我的经验，任何可用于从抽象模型生成文档的工具都可以用于此目的。

我不知道您的 API 生态系统如何，但对我有用的是拥有一份对 REST 进行温和介绍的通用文档，解决一些误解，以及您的模式的详细一般用法，应该适用于任何 API .之后，每个单独的服务器都应该有自己的文档，重点是媒体类型。

我不喜欢在 text/html 中返回文档的想法表示，因为它应该表示资源本身，但我喜欢使用 rel:doc 链接指向该媒体类型的 HTML 文档的想法。