用于记录RESTful API的标准方法

Question

我正在为新的内部Web服务编写RESTful API规范.这不是很长很简单,但即便如此,这是我第一次使用严格的REST(而不是出于实际原因作弊 - 避免PUT,DELETE因为它们是PHP的痛苦,等等).我想知道是否有任何标准方法或最佳实践来记录REST接口？我希望团队的其他成员能够一目了然地理解它,对于任何想要编写客户端的人来说,如果不了解底层代码就能够这样做.

Answer 1

当然,REST API理想情况下应该使用HATEOAS并且是超文本驱动的(大量使用媒体类型),但也有简单的人性化文档供开发人员使用,这是有帮助的.

一些有助于生成这样的文档的特定工具:

• 昂首阔步
  • 用于描述REST API的开放规范[ github ]
  • 自动生成工具
    • 文档
    • 您的API代码
  • 捐赠给OpenAPI计划,并于2015年更名为OpenAPI
• Mashery
  • 一个开源项目[ github ]
  • 生成工具
    • 文档
    • API的探索界面
• 蜂房和API蓝图
  • 在降价时在DSL中写入API描述
  • 自动生成工具
    • 文档
    • 模拟服务器
  • 似乎专注于ruby + mac devs
• 肾错构瘤
  • 描述REST API的规范[ github ]
• WADL
  • 使用XML编写可发现的API文档的规范
  • 一些讨论比较WSDL和WADL
• APIgee
  • 具有一些文档功能的商业产品
• 3比例
  • 具有一些文档功能的商业产品
• miredot
  • 商业REST API文档生成器
  • 特定于Java

Answer 2

我一直在使用http://apiary.io,这非常好.您还可以将API文档导出到github.

Answer 3

在罗伊的帖子中,他说

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

Answer 4

一个好的ReST文档意味着记录您的媒体类型和仅媒体类型.

在典型的场景中,您将生成如下文档:

Acme Corp XML格式

链接发现

文档中描述了各种资源的链接,可以通过在书签URI(通常是服务器的根目录,http://www.acme.org)上向服务器发出GET或HEAD请求来查找,并查找HTTP链接头:

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

其中rel部分是链接关系,并且xxx是已建立关系的URI.

链接关系

本文档定义了以下关系名称:

• http://rel.acme.org/services 链接关系描述了可以导航的链接列表.
• http://rel.acme.org/customers 使用此关系的链接是客户列表.

媒体类型

这application/vnd.acme.services+xml是一个带有xml序列化的文档,它描述了应用程序可能要处理的链接列表.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

这applcation/vnd.acme.customers+xml是一个带有xml描述客户的序列化的文档.

示例文件:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

等等...

关键是要让开发人员遵循您定义的链接.首先找到索引的链接,以便他们可以获取他们可以导航到的内容列表.

一旦他们发现该文档,他们就会发现他们可以在某个Uri上看到一个客户列表,并且可以对其进行GET反对.

如果他们找到感兴趣的客户,他们可以按照中定义的链接/customers/customer/@href发布GET并检索该客户的代表.

从那里,您的媒体类型可以使用更多链接嵌入用户可用的操作.您还可以选择在资源上发出OPTIONS请求以了解是否允许删除资源,或者如果您可以在修改后保存文档,则可以选择PUT.

所以一个好的文档永远不会:

• 给静态链接
• 进行交互,例如"您可以使用此媒体类型向客户发布POST,这将意味着移动操作".客户端应该仅针对Customer发出POST,因为您的XML文档已经以这种方式指定了它.

所有这一切的要点是实现客户端和服务器之间的最小耦合.客户端可以非常智能地显示和发现资源(显示表单和上帝知道还有什么),但对于实际工作流程是完全愚蠢的:服务器决定.

Answer 5

在我的公司，我们非常高兴使用WADL（Web 应用程序描述语言）。维基百科将其描述为：“一种基于 XML 的文件格式，提供基于 HTTP 的 Web 应用程序的机器可读描述”。我发现原始 WADL 易于编写、阅读和理解，并且它直接映射到 RESTful 概念。官方项目提供了简单的规范、XSD 和 RELAX NG 模式以及 Java 工具。

有许多工具和资源可用于使用 WADL，包括：

• wadl_stylesheets，XSLT 样式表，用于从 WADL 文件创建 HTML 文档
• Restlet是一个用于构建 RESTful 服务器和客户端的 Java 框架，包含 WADL 扩展

doc提示：尝试使用XHTML 命名空间，通过包含 HTML 元素，在 WADL 文档的元素中包含人类可读的文档，例如描述、概念、入门、使用提示等。它可以产生很大的不同！