Developer Painkiller: Interactive API Docs

Neil Mansilla is Director of Developer Products and API Evangelist for Mashery. Mashery is a ProgrammableWeb sponsor.

Developers are game changers. Developers are craftspeople. Like all smart, motivated tinkerers who like to make stuff, developers also tend to have strongly-held opinions about what makes their craft easier or more difficult. Developer pain tiers upwards from mildly annoying to “bang head here” WTF. Debugging someone else’s sloppy code or terminal sessions timing out? Non-awesome. Coworkers talking loudly on the phone near their desk or standing over their shoulders? Painful. Awful Documentation? Excruciating.

In the world of web APIs that numbers over 3000 and growing rapidly, developer surveys conducted by Mashery and other parties clearly show that poor documentation is public enemy number one. And don’t think that the perpetrators are understaffed, underfunded startups. Even the most bleeding edge, well-funded Silicon Valley tech companies serve up atrocious API docs.

To address this problem, there are new tools and trends in this space that are helping both API providers: tool-generated documentation and interactive interfaces. The rest of this article will discuss the challenges of traditional API documentation and how implementing new tools can help API providers deploy next generation docs that will knock developers’ socks off.

The Difficulty of Crafting and Maintaining Great API Docs

Writing fantastic documentation is rarely a top-priority when it comes to any software project. Project managers and engineers realize the importance of providing clear, concise and complete docs -- but typically, docs are an afterthought that get bumped down as deadlines approach. Why is something as critical as documentation treated like a third-class citizen? Because crafting and maintaining outstanding docs are no easy tasks.

Documenting a Web API poses a particularly difficult challenge in that developers build apps on a variety platforms and languages. Add to that SDKs, and you end up with even more documentation to write. Web APIs are intended to be Platform and language agnostic, however, conventions and parlance do not always translate clearly to all developers.

Developers cherish API call examples and Sample Code within documentation. Learning by example is one of the most common patterns in assimilating new coding skills. However, keeping examples up to date with the latest version of the API poses a maintenance challenge. Non-working examples due to API changes and deprecation can frustrate developers to the point dropping the API from projects completely.

It’s also important to consider the cost of poor API documentation. Developer technical support can be high bandwidth due to the uniqueness of implementation. Lastly, the opportunity cost of providing poor documentation is immeasurable when considering lost innovations and partnerships.

Tools to the Rescue

Automating the documentation process is not a new concept. SOAP based web services built on WSDL files can take advantage of tools such as soapUI, TechWriter and XMLSpy to help build docs and provide interactive testing/debugging tools. Tools like Javadoc generate API documentation from comments in Source Code. However, with the rise of the web API becoming more mainstream, there has largely been a departure from SOAP and a wider adoption of the simpler RESTful style of web services.

In the RESTful Web Service world, there is no de facto of definition file formats such as SOAP’s WSDL. API providers that do not use formal definition files are left with the options of rolling their own tools to generate documentation or writing documentation manually. The latter is the most common scenario.

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.

Changing the Game for Developers

I/O Docs is not rocket science. All Mashery has done is made solving developer pain a priority. This means we did not let other priorities bump it off our to-do list. Couldn’t be simpler. The most common (and gratifying) feedback we’ve received about I/O Docs is the praise you want to hear from experts in their craft: “this just makes sense.” The benefits of tool-generated interactive documentation for API providers speak for themselves – ease of deployment with simple JSON schema, ease of maintenance, and reduction in technical support. And for developers, the benefits are plentiful – a clean consistent interface, ability to execute live APIs calls for accelerated learning, method exploration, and testing from a single location. If you manage a web API or your development heavily relies upon one, I encourage you to advocate for, or implement tool-generated and interactive documentation to benefit the entire platform’s ecosystem.

Be sure to read the next Best Practices article: The Six Pillars of Complete Developer Documentation