InfoQ

InfoQ

InfoQ

En | 中文 | 日本語 | Br

592,113 Apr unique visitors

News

My Bookmarks

Login or Register to enable bookmarks for unlimited time.

The content has been bookmarked!

There was an error bookmarking this content! Please retry.

Mashery Redefines API Documentation with Interactive I/O Docs

Posted by Jeevak Kasarkod on Jul 26, 2011

Sections
Enterprise Architecture,
Architecture & Design,
Development
Topics
API ,
Tools ,
SOA ,
REST ,
Architecture ,
Enterprise Architecture ,
Agile ,
Documentation ,
Programming

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. 

 

  • This article is part of a featured topic series on SOA and also Agile

No comments

Watch Thread Reply