BT

Mashery Redefines API Documentation with Interactive I/O Docs

by Jeevak Kasarkod on Jul 26, 2011 |

On July 25 2011, Mashery announced the release of the I/O Docs tool, the latest addition to the Mashery API Management SaaS platform. I/O Docs aims to equip developers with an interface to a live API within the API documentation itself with the intent to accelerate adoption.

InfoQ spoke with Neil Mansilla, director of product management at Mashery regarding the tool and its features.

InfoQ: What is I/O Docs and what is the motivation behind this project?

Mashery I/O Docs is interactive documentation that helps developers to understand and learn how to use APIs more quickly and effectively. Live API calls can be made directly within the documentation, providing realtime payload data as opposed to static examples. I/O Docs helps our customers, API providers, publish documentation that is clean, simple in appearance, yet full of granular details at the resource, method and parameter levels.
In our surveys we learned that API docs often lacked specificity around methods and API call examples. With Mashery I/O Docs, the anatomy of the method, down to parameter level, is defined and clearly displayed for the developer. As for API call examples, I/O Docs is a living example generator — allowing developers to create their own examples on-the-fly with live API calls.Our motivations behind I/O Docs are to help our customers' platforms and developers succeed.

The press release includes a list of additional  benefits for API providers:

- Clear API documentation, testing, debugging and exploration, all in one place
- Shorter time to a developer's first API call
- Faster application development
- Reduced tech support
- A powerful channel for internal tech support, QA and tech writers to communicate API changes
- Assurance that API documentation reflects current API versions
- Clean, beautiful API documentation design

InfoQ: Is this tool equally applicable for both public APIs and APIs within an enterprise? Does it support non-RESTful APIs?

Mashery I/O Docs is available for both private enterprise and public APIs. Mashery I/O Docs currently supports RESTful APIs. SOAP support within I/O Docs will be available soon. Mashery I/O Docs is extensible and can be adapted to support non-standard protocols.

InfoQ: Can you share some technical details involved in moving a traditional API documentation, say from Java Docs to I/O Docs?

Mashery I/O Docs uses a JSON schema to describe APIs resources, methods and parameters. The schema is extensible to handle unique characteristics of various APIs. Creating a JSON configuration for I/O Docs is straightforward.
InfoQ:  Any future roadmap plans for IO Docs that you want to share with the community?
Our roadmap around I/O Docs includes: support for additional encryption methods, support for SOAP, ability to deploy anywhere (even outside of the Mashery stack).
Some early I/O docs implementations that are publicly available include API documentation from Klout, Alibris and Fanfeeder

 

Hello stranger!

You need to Register an InfoQ account or to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2013 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT