Smarter API Documentation Puts Inputs and Outputs Inline

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

Be sure to read the next Best Practices article: Developer Painkiller: Interactive API Docs