Smarter API Documentation Puts Inputs and Outputs Inline

Kin Lane
Jul. 26 2011, 11:00AM EDT

To 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

Kin Lane I am a programmer and entrepreneur, with a focus on the business of APIs. I study how APIs are changing the business landscape, and the rise of API driven developer ecosystems. I share my insights by blogging on API Evangelist and ProgrammableWeb, and put into action as API evangelist for CityGrid.

Comments

Comments(4)

[...] 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. [...]