Web API documentation gets interactive with Mashery I/O Docs

Mashery has announced the open sourcing of its Mashery I/O Docs, a documentation system for generating interactive information about how Web APIs work. I/O Docs is inspired by Posterous's API reference and the Wordnik documentation. Examples of I/O Docs in use are available for the Alibris API and Klout API.

Once the documentation is generated and loaded into a web browser, the various API calls are listed on a page in quick reference form. Clicking on any one of them expands the entry to show the parameters the call will take. Rather than being a passive display, the parameters have value form fields, a selector for results in XML or JSON format, and a "Try It" button that will make that API request with the parameter values shown. It will display the complete call being made and the response headers and body.

This format allows developers to experiment with the API to gain a better understanding of how it works. The open sourced system, written as a Node.js application, is available to clone from Github under an MIT style licence. I/O Docs doesn't automate generating the documentation but requires that the developer create JSON files which contain information on how the API operates. I/O Docs can also support basic key authentication and "three-legged" OAuth, for documenting access controlled APIs.

(djwm)