RESTful API文档

我将很快devise一个RESTful API,因此我需要描述它以使其他人能够开始使用它来实现客户端。

我查了一下,但不幸的是,我还没有发现任何描述基于Web的RESTful服务的标准化forms。 我要找的东西就像JavaDoc,尽pipe它不一定要用任何代码生成。 我也不是在谈论像WADL这样的东西,我宁愿要有一些我可以分发的人类可读文档。

由于RESTful基于Web的服务的性质,标准化文档应该相当容易。 它应该只列出可用的资源,相应的URI,允许的方法,内容types并描述可用的操作。 你有什么build议吗?

在此先感谢和问候

由于RESTful基于Web的服务的性质,标准化文档应该相当容易。 它应该只列出可用的资源,相应的URI,允许的方法,内容types并描述可用的操作。 你有什么build议吗?

这绝对是关于loggingREST服务的错误方法。

一个统治他们的URI

您不应该枚举资源的URI,因为这会鼓励客户端将这些URI硬编码到客户端代码中。 这会在客户端和服务器之间造成不必要的耦合。 应根据从服务根URI导航来发现URI。 根URI是唯一应该logging的URI。 文档应着重描述返回的表示中的信息和链接。 如果从以根URI返回的表示forms开始,则可以描述介质types以及该文档中可能提供的链接。

别名您的URI

使用某种别名在客户端和服务器之间创build一个间接层非常重要。 如果遵循atom:link标准来定义链接,那么rel属性将成为标识符。 然而,还有其他的方式来定义链接,例如,图像embedded在HTML中的方式。 一个图像标签可以有一个Id和一个href。 Id标签应该用来标识你想要访问URL的图像。

媒体types定义您的API

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

所以你可能会问,有什么区别? 为什么不创build端点列表? 这是几个原因,

可更改的URI空间

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

dynamic分配

这不仅是您可以更改的URI的path部分。 你也可以改变主机。 想象一下,您的应用开始获得比预期更多的使用,您可以轻松地将所有图像或video资源的主机更改为指向不同的服务器。 你甚至可以通过返回不同的主机提供简单的负载平衡。 由于RESTful API是无状态的,因此哪个服务器响应请求确实无关紧要。 此function对于如此多的场景非常有用:将HTTPS内容移动到专用服务器上,根据客户端位置在地理上分配请求,将应用程序的function垂直划分到不同的服务器上。

显式协议

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

你不能自动化有趣的东西

为什么大多数自动化文档loggingREST服务的原因是无效的,因为统一的界面不需要logging简单的东西。 一旦理解了HTTP(请参阅RFC2616),就可以了解API的所有机制。 剩下的就是无法生成的真正有趣的域特定信息。

看好的一面,文件应该更短。 任何额外的可用时间应该用于提供如何在常见场景中导航API的示例。

没有标准,只是一个公开的辩论。 InfoQ有一篇有趣的文章: 描述RESTful应用程序 。

如果您使用类似JAX-RS的东西,您可以使用实际的JavaDoc作为参考。 或者做注释扫描并自动生成它也不应该太难,尽pipe我不知道具体的实现。

如果您使用的是MVC模式,则URL通常表示为:

example.com/class/function/ID

这些都是实用可访问的信息,这意味着您仍然可以使用JavaDoc并能够loggingRESTful方法,因为URL的每个部分都连接到源代码本身。