Web 服务的文档标准/结构/风格 [关闭]

Question

谁能推荐 Web 服务高级文档指南？

这个文档应该可以让那些不了解特定 Web 服务的人对它存在的原因、它的路线图和它的使用示例有一个基本的了解。

此类文档应适合打印在 A4/Letter 纸的两面，并且需要不到 10 分钟的时间来阅读。

请注意，这是对开发人员用来使用该接口的低级 API 文档的补充。

Answer 1

我不确定我是否有指导方针，但我可以向您展示一个我发现是一组很好的 Web 服务 API 文档的示例。

http://www.flickr.com/services/api/

Flickr API 页面以非常易读的形式列出。这个页面主要有：

• 概述页面的链接
• 写入常见方案（在这种情况下上传照片）
• 有关使用 API 的工具的信息
• 每种API方法的详细描述，由活动分组

特别是，描述常见访问模式（上传照片、替换照片）的页面对我来说至关重要。它们向 API 的使用者展示如何执行常见操作以及您期望人们如何使用您的 API。最后一点很重要 - 您想说“嘿，我们希望您像这样打电话给我们，使用这些方法，并进行这种错误处理”。向您的用户展示一些有关 API 使用的最佳实践，您将节省大量的支持电话。