BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

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

| 作者 Jeevak Kasarkod 关注 3 他的粉丝 ,译者 吴宇 关注 0 他的粉丝 发布于 2011年7月31日. 估计阅读时间: 3 分钟 | ArchSummit北京2018 共同探讨机器学习、信息安全、微服务治理的关键点

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文档实现已经可以公开获得了,其中包括从KloutAlibris以及Fanfeeder获取API文档。 

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

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我
社区评论

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT