loggingRESTful API的标准方法
我正在为一个新的内部Web服务编写一个RESTful API的规范。 这不是很长很简单，但即使如此，这是我第一次使用严格的REST（而不是作弊的实际原因 – 避免PUT和DELETE因为他们是一个PHP的痛苦，等等）。 我想知道是否有任何标准的方法或loggingREST接口的最佳做法？ 我希望团队的其他成员能够一目了然地了解它，并且对于任何想要编写客户端的人来说，都能够理解底层代码。
在罗伊的职位上，他说
REST API应该花费几乎所有的描述性努力来定义用于表示资源和驱动应用程序状态的媒体types，或者为现有标准媒体types定义扩展关系名称和/或启用超文本的标记。 用于描述在感兴趣的URI上使用什么方法的任何努力应该在媒体types的处理规则的范围内（并且在大多数情况下已经由现有媒体types定义）完全定义。
当然， REST API理想情况下应该使用HATEOAS并且是超文本驱动的 （大量使用媒体types），而且为开发人员提供简单的人性化文档是很有帮助的。
一些有助于生成文档的特定工具如下所示：
- 昂首阔步
- 描述REST API的开放规范[ github ]
- 自动生成工具
- 文档
- 代码为您的API
- Mashery
- 一个开源项目[ github ]
- 生成工具
- 文档
- 您的API的探索界面
- 蜂房和API蓝图
- 用markdown在DSL中编写API描述
- 自动生成工具
- 文档
- 模拟服务器
- 似乎专注于ruby + mac开发者
- 肾错构瘤
- 描述REST API的规范[ github ]
- WADL
- 用XML编写可发现的API文档的规范
- 一些讨论比较WSDL和WADL
- APIgee
- 具有一些文档function的商业产品
- 3比例
- 具有一些文档function的商业产品
- miredot
- 商业REST API文档生成器
- Java的具体
我一直在使用http://apiary.io ，这很不错。 您也可以将API文档导出到github。
一个好的ReST文档将意味着logging你的媒体types和只有你的媒体types。
在一个典型的情况下，你会产生一个像这样的文件：
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是已build立关系的URI。
链接关系
本文档定义了以下关系名称：
媒体types
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>
等等…
重点是让开发者遵循你定义的链接。 首先find索引的链接，以便他们可以得到他们可以导航到的东西的列表。
一旦他们发现了这个文件，他们就会发现他们可以在某个Uri上看到一个客户列表，并且可以对它做一个GET 。
如果他们find感兴趣的客户，他们可以按照/customers/customer/@href定义的链接进行操作，并发出一个GET来检索该客户的表示。
从那里，您的媒体types可以embedded用户可用的操作，使用更多的链接。 您还可以select在资源上发出OPTIONS请求，以了解是否允许删除资源，如果可以在修改后保存文档，还可以selectPUT。
所以一个好的文档永远不会：
- 给静态链接
- 给予互动，如“你可以在这个媒体types的客户发布POST，这将意味着移动操作”。 客户端应该只针对客户发布POST，因为您的XML文档已经这样指定了它。
所有这一切都是为了实现客户端和服务器之间的最小耦合。 客户可以非常聪明地展示和发现资源（展示forms，上帝知道还有什么），但对于实际的工作stream程是什么：服务器决定是完全愚蠢的。
在我的公司，我们一直很高兴使用WADL ，Web应用程序描述语言。 Wikipedia 将其描述为：“一种基于XML的文件格式，提供了基于HTTP的Web应用程序的机器可读描述”。 我发现原始的WADL易于编写，阅读和理解，并且直接映射到RESTful概念。 官方的项目提供了一个简单的规范，XSD和RELAX NG模式，以及Java工具。
存在与WADL一起工作的一些工具和资源，包括：
- wadl_stylesheets ，用于从WADL文件创buildHTML文档的XSLT样式表
- Restlet是一个用于构buildRESTful服务器和客户端的Java框架，它包含一个WADL扩展
小窍门：使用XHTML命名空间，通过包含HTML元素，在WADL文档的doc元素中尝试包括人类可读的文档，例如描述，概念，入门，使用技巧等。 它可以有很大的不同！
最初，我们去静态资源的文件，但只是太多的问题。 最后，我们转而使用IO / Docs（实际上是一个分叉 ）使用Live文档页面。 一直很好。
你可能会发现rest-tool很有用。
它遵循语言不可知的方法来编写规范，模拟实现和自动化RESTful API的unit testing。 它也提供了一本烹饪书，但是它的内容在不断增长。
您刚刚描述的服务可以立即使用，因此也适用于实验。
为了创build理解/文档，重量级解决scheme并不总是需要的。 （很棒）重量级工具的例子是：IO / Docs / Apigee（虽然很棒的工具）。
对于已经具有docchain设置的小型项目（doxygen / phpdoc / phpdoctor / custom / etc），我使用下面的shellscript将页面包含在完整生成的文档中：
https://gist.github.com/4496972
演示： http : //pastie.org/5657190
它只是在你的源代码中使用自定义评论标签。 它也可以是logging任何源代码（语言）的一个很好的起点。
