RESTful API 文档

Question

就目前情况而言，这个问题不太适合我们的问答形式。我们希望答案得到事实、引用资料或专业知识的支持，但这个问题可能会引发辩论、争论、民意调查或扩展讨论。如果您觉得这个问题可以改进并可能重新开放， visit the help center以获得指导。

已关闭 11 年前。

我很快就要设计一个 RESTful API，因此我需要描述它，以便其他人能够开始使用它来实现客户端。

我环顾四周，但不幸的是，我没有找到任何描述基于 Web 的 RESTful 服务的标准化形式。我正在寻找类似 JavaDoc 的东西，尽管它不必由任何类型的代码生成。我也不是在谈论像 WADL 这样的东西，我宁愿拥有一些可以分发的人类可读文档。

由于 RESTful 基于 Web 的服务的性质，标准化文档应该很容易。它应该只列出可用资源、相应的 URI、允许的方法、内容类型并描述可用的操作。因此您有什么建议吗？

提前致谢并问候

Answer 1

Due to the nature of RESTful web-based services, it should be quite easy to standardize a documentation. It should just list available ressources, corresponding URIs, allowed methods, content-types and describe the availabe actions. Do you have any suggestions therefore?

这绝对是记录 REST 服务的错​​误方法。

一个 URI 来统治它们

您永远不应该枚举资源的 URI，因为这会鼓励客户端将这些 URI 硬编码到客户端代码中。这会在客户端和服务器之间产生不必要的耦合。应基于从服务根 URI 进行导航来发现 URI。根 URI 是唯一应该记录的 URI。文档应重点描述返回的表示中包含哪些信息和链接。如果您从根 URI 返回的表示开始，您可以描述媒体类型以及该文档中可能提供的链接是什么。

为您的 URI 起别名

使用某种别名在客户端和服务器之间创建间接层非常重要。如果您遵循atom:link 标准来定义链接，那么rel 属性将成为标识符。然而，还有其他定义链接的方法，例如将图像嵌入 html 中的方法。图像标签可以有 Id 和 href。 Id 标签应用于识别您希望访问其 URL 的图像。

媒体类型定义您的 API

最终结果是您在某种表示的上下文中定义 API 中的所有端点。完整的 API 由一组返回的表示和连接它们的链接定义。

那么你可能会问，有什么区别呢？为什么不直接创建端点列表呢？原因有以下几点:

可更改的 URI 空间

由于客户端使用别名访问这些链接，因此您网站的整个 URL 结构可以完全更改，而不会影响客户端。这使得所有无休无止的“构建我的分层 URL 的最佳方式是什么”问题几乎变得无关紧要。您可以尝试一种方法，如果不起作用，只需更改它，您不会破坏任何客户端代码或必须更改任何文档!

动态分布

您不仅仅可以更改 URI 的路径部分。您也可以更改主机。想象一下，您的应用程序开始获得比您预期更多的使用量，您可以轻松更改所有图像或视频资源的主机以指向不同的服务器。您甚至可以通过返回不同的主机来提供简单的负载平衡。由于 RESTful API 是无状态的，因此哪个服务器响应请求并不重要。此功能对于很多场景都很有用:将 HTTPS 内容移动到专用服务器上、根据客户端位置在地理上分配请求、将应用程序的功能垂直划分到不同的服务器上。

显式协议(protocol)

仅仅因为表示可能会返回链接，并不意味着它总是会返回。服务器只能返回基于当前资源状态允许的链接。当与服务器资源交互时需要遵循特定协议(protocol)时，这非常有用。客户端代码不需要了解协议(protocol)规则，它只需向用户呈现服务器已提供的链接即可。

你无法自动生成有趣的东西

大多数记录 REST 服务的自动化工作之所以无效，是因为统一的接口(interface)消除了记录简单内容的需要。一旦了解了 HTTP(请参阅 RFC2616)，您就了解了 API 的所有机制。剩下的就是无法生成的真正有趣的特定领域信息。

往好的方面看，文档应该会短得多。任何额外的可用时间都应该用于提供如何在常见场景下导航 API 的示例。