RESTful API文档 [英] RESTful API Documentation

问题描述

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

I'm going to design a RESTful API soon, thus I need to describe it in order to enable other people to start implementing clients using it.

我已经看了一下，但遗憾的是，我还没有发现任何描述基于Web的RESTful服务的标准化形式。我要找的是JavaDoc，虽然它不必由任何代码生成。我也没有谈论像WADL这样的东西，而是希望得到一些可读的文件。

I've looked around a bit, but unfortunately, I've not found any standardized form of describing web-based RESTful services. What I'am looking for is something like JavaDoc, although it don't have to be generated out of any sort of code. I'm also not talking about something like WADL, I rather want to have some human-readable documentation I can hand out.

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

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?

提前感谢！ greets

Thanks in advance & Greets

推荐答案

由于RESTful基于web的
服务的性质，相当容易的
标准化文档。它应该
只列出可用的资源，
对应的URI，允许的方法，
内容类型和描述
的可用性操作。你有没有
的建议吗？

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服务。

This is absolutely the wrong way to go about documenting REST services.

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

You should never enumerate URIs of the resources because that would encourage a client to hard code those URIs into the client code. This creates unnecessary coupling between the client and the server. URIs should be discovered based on navigating from the services root URI. The root URI is the only URI that should be documented. The documentation should focus on describing what information and links are in the representations that are returned. If you start with the representation that is returned from the root URI, you can describe the media type and what are the links that may be provided in that document.

使用某种别名在客户端和服务器之间创建一个间接层很重要。如果遵循原子：链接标准来定义链接，则rel属性将成为标识符。然而，还有其他定义链接的方法，例如图像嵌入到HTML中的方式。图像标签可以具有Id和href。 Id标签应用于标识您要访问的URL的图像。

It is important to use some kind of alias to create a layer of indirection between the client and the server. If you follow the atom:link standard for defining links then the rel attribute becomes the identifier. However, there are other ways of defining links, like, for example, the way images are embedded in html. An image tag can have an Id and a href. The Id tag should be used to identify the image that you wish to access the URL for.

最终的结果是您定义API中的所有端点一些表示的背景。完整的API由返回的表示集和连接它们的链接定义。

The end result is that you define all the endpoints in your API within the context of some representation. The complete API is defined by the set of returned representations and the links that connect them.

所以你可能会问，有什么区别？为什么不创建端点列表？以下是几个原因：

So you may ask, what is the difference? Why not just create the list of endpoints? Here are a few reasons,

因为客户端使用别名访问这些链接，这允许您的网站的整个URL结构完全可变，而不会影响客户端。这使得所有无休止的什么是最好的方式来构造我的分层URL的问题几乎无关紧要。您可以尝试一种方式，如果不起作用，只需更改即可，不会破坏任何客户端代码，也不得更改任何文档。

Because those links are accessed by the client using an alias, this allows the entire URL structure of your site to be completely changeable without impacting the client. This makes all of the endless "what is the best way to structure my hierarchical URL" questions pretty much irrelevant. You can try it one way, and if it doesn't work, just change it, you won't break any client code or have to change any documentation!

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

It is not just the path part of the URI that you can change. You could also change the host. Imagine that your app is starting to get a lot more usage than you expected, you can easily change the host of all image or video resources to point to a different server. You could even provide simple load balancing by returning different hosts. As RESTful APIs are stateless, it really does not matter which server responds to the request. This feature is useful for so many scenarios: moving HTTPS stuff onto a dedicated server, geographically distributing requests based on client location, vertically partitioning functions of the application onto different servers.

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

Just because a representation may return a link, does not mean that it always will. The server can only return the links that are allowed based on the current resource state. This can be really helpful when there is a specific protocol that needs to be followed when interacting with a server resource. The client code does not need to understand the rules of the protocol, it can just present to the user the links that have been made available by the server.

大多数自动化文档记录REST服务的原因不在有效的是因为统一的界面消除了记录简单的东西的需要。一旦您了解HTTP（参见RFC2616），您将了解API的所有机制。剩下的只是无法生成的真正有趣的域名具体信息。

The reason why most automated efforts to document REST services are not effective is because the uniform interface removes the need to document the easy stuff. Once you understand HTTP (see RFC2616) you understand all of the mechanics of the API. All that is left is the really interesting domain specific information that cannot be generated.

看看明亮的一面，文档应该更短。任何额外的可用时间应用于提供如何导航API的常见情况的示例。

Look on the bright side, the documentation should be much shorter. Any extra available time should be spent on providing examples of how to navigate the API for common scenarios.

这篇关于RESTful API文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！