Redesigning Docs for RESTful Web APIs
In the past year, a new trend has emerged for web API documentation – the interactive interface. It is a simplified hybrid view that allows for learning, exploration and testing in one location. Long-form documentation is being complimented, if not completely replaced, by tool-generated hybrid interfaces.
Companies such as Posterous, Wordnik and Google have led this new trend with their own hybrids of documentation and exploration tools. The latter two have defined their API resources, methods, parameters and authentication schemes into custom JSON service definition schemas. They have also created tools that generate interactive docs driven by these schemas.
At Mashery, we were inspired by these new designs to build our tools. Mashery manages hundreds of APIs for companies worldwide, so finding a standard service definition schema that fit all of them was impossible. Instead, we crafted a generic and extensible JSON schema capable of handling the numerous variations. We developed a prototype in Node.js (server-side JavaScript) that automatically renders interactive docs based on the definition file. The reception from our beta testing clients and developers was extremely positive.
As soon as Mashery launched I/O Docs into the enterprise production stack, several customers enabled the new interactive documentation, including Alibris, Klout, FanFeedr and YellowAPI. There are many other Mashery-managed APIs that will be enabled with I/O Docs over the next several weeks. However, many platforms who are not customers of Mashery reached out, asking how they might get I/O Docs deployed for their platforms. This demand led to our second API documentation inspiration.
Mashery decided to open-source I/O Docs on GitHub so that others can utilize and contribute to the project. The project has been quite active with a number companies testing and building upon it. For instance, SimpleGeo, a platform for location-based data, has already deployed I/O Docs for their developer community.
