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.