Smarter API Documentation Puts Inputs and Outputs Inline

Kin Lane, July 26th, 2011

MasheryTo support the demand for better API documentation, Mashery, a provider of API management and strategy services, launched a new set of API documentation tools. The new feature is a combination of API documentation and an API explorer, allowing developers to make requests on an API inline while browsing the API reference materials.

Lack of quality documentation is a major stumbling point for developers when looking to integrate with an API, according to Peter Gruenbaum, founder of SDK Bridge:

SDK Bridge set out to find out what is most important to the people who use APIs by sending out a survey and asking them. We found, not surprisingly, that many thought that documentation could be better. When asked to rate quantitatively, people rated overviews, sample code, and API references the highest, followed closely by tutorials.

Mashery’s new feature, I/O Docs, provides documentation, testing, debugging and exploration, all in one place. Then company says developers can shorten time it takes to make their first API call and reduce overall technical support around an API. The feature is available to API providers who are Mashery customers and can already be seen in documentation for the Klout API, Alibris API and Fanfeedr API.

“Creating useful and clear API documentation can be challenging,” says Mashery director of product management Neil Mansilla. “Mashery I/O Docs makes it easy to offer a powerful, interactive API learning experience.” Mansilla provides an overview of I/O Docs in the video embedded below.

More interactive documentation options have become popular recently. Mashery competitor Apigee has a console that any provider can use to help developers understand an API. Similarly, Google has its Google API explorer for many of its own APIs, built on the Google APIs Discovery API.

For particular API profiles, there is also “try it” functionality embedded right on ProgrammableWeb’s site. For example, try out Twilio and several Google APIs.

Disclosure: Mashery is a ProgrammableWeb sponsor

Both comments and pings are currently closed.

4 Responses to “Smarter API Documentation Puts Inputs and Outputs Inline”

August 2nd, 2011
at 12:20 pm
Comment by: Mashery Open Sources Their API I/O Docs | API Evangelist

[...] week at OSCON, I wrote about Mashery’s release of their new I/O Docs. Mashery I/O Docs are a combination of API documentation and an API explorer, allowing developers [...]

August 23rd, 2011
at 11:10 pm
Comment by: Conditional API Documentation | API Evangelist

[...] Masherys I/O docs, and smart API documentation allow developers to make API calls from within the documentation, making learning about APIs more interactive. This is a great approach to help developers learn about APIs, but I think we can go even further. [...]

December 2nd, 2011
at 7:07 pm
Comment by: Click-to-Cloud: Facebook Helps Heroku Add a Half Million Apps in 2011

[...] as API consoles and inline “try it” functionality has re-birthed API documentation, click-to-cloud is the new sample app. Click-to-cloud requires no [...]

July 17th, 2012
at 12:00 pm
Comment by: Today in APIs: StormPath, Mashery and 16 New APIs

[...] year at OSCon, Mashery (a ProgrammableWeb sponsor) released its interactive documentation project (I/O Docs) as open source. This year, it’s expanding upon the tool with a new project for [...]

Follow the PW team on Twitter

APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.