交互式 I/O 文档——Mashery 重新定义 API 文档

阅读数:1562 2011 年 7 月 29 日

话题:SOAREST语言 & 开发架构

Mashery 于 2011 年 7 月 25 日发布了其 I/O 文档工具,这也是对 Mashery API 管理 SaaS 平台提供的新增支持。I/O 文档旨在为开发人员提供一个接口,通过该接口可以直接在 API 文档中执行实时 API 调用,从而实现加速应用。

针对该工具及其特点,InfoQ 对 Mashery 产品管理主管 Neil Mansilla 进行了采访。

InfoQ:什么是 I/O 文档?该项目的动因又是什么呢?

Mashery I/O 文档是一种交互式的文档,可以帮助开发人员更加快速有效地理解和学习 API。我们可以直接从 API 文档执行实时的 API 调用,相较干巴巴的静态示例这种方式可以提供实时的载荷数据。I/O 文档能够帮助我们的客户和 API 提供者,这样发布的文档外观清晰、简洁,且在内容资源、方式方法和参数层面又能够做到细致入微。

在我们此前的调研中,我们了解到 API 文档通常缺乏方法上的专用性和 API 调用样例。使用 Mashery I/O 文档,对方法的分析,可深入到参数层次,从而为开发人员良好地定义并清晰地展现出来。至于 API 调用样例,I/O 文档就是个实时样例生成器——通过实时 API 调用,开发人员能够创建自己直接可运行的样例。我们推出 I/O 文档的动因就是希望能够帮助我们客户的平台和开发人员取得成功。

下面列举了该工具其他一些对 API 提供者带来的好处:

- 清晰的 API 文档,测试、调试以及开发都集中在一起

- 缩短开发人员首次 API 调用时间

- 更快的应用开发

- 减少技术支持

- 具备一个强大的沟通渠道可供内部技术支持、QA 以及技术写手来实现与 API 变更的交流

- 确保 API 文档反应当前的 API 版本

- 清晰、优美的 API 文档设计

InfoQ: 该工具是否同样适用于公共 API 和企业内部 API 呢?是否支持非 REST(non-RESTful)APIs?

Mashery I/O 文档对私有企业 API 和公共 API 都适用。Mashery I/O 文档目前支持 RESTful APIs。很快 I/O 文档将实现对 SOAP 的支持。Mashery I/O 文档是可扩展的,并且能够适用于支持非标准的协议。

InfoQ:能否请您描述一下有关将一个传统 API 文档,比如 Java 文档,迁移到 I/O 文档的相关技术细节?

Mashery I/O 文档使用一种 JSON schema 来描述 API 资源、方法和参数。该 schema 可被扩展来处理各种 API 的各种独到特征。创建一个面向 I/O 文档的 JSON 配置是最直截了当的方法。
InfoQ:

还有什么有关 IO 文档未来发展蓝图是您觉得可以与社区分享的吗?



我们的 I/O 文档发展蓝图包括:提供补充加密方法的支持、支持 SOAP、能够实现随地部署(甚至在 Mashery 环境堆栈以外)。

一些早期的 I/O 文档实现已经可以公开获得了,其中包括从

Klout

Alibris

以及

Fanfeeder

获取 API 文档。 

 查看英文原文:Mashery Redefines API Documentation with Interactive I/O Docs