The Importance of API Documentation

Since APIs are designed to be consumed, it is important to make sure that the client, or consumer, is able to quickly implement an API and understand what is happening with it. Unfortunately, many APIs make implementation extremely difficult, defeating their very purpose. As you build out your API you want to ensure that you not only provide informational API documentation to help your developers integrate/ debug connections, but also return back relevant data whenever a user makes a call—especially a call that fails.

While having a well formatted, coherent body response in your API documentation is extremely important (you want something that can easily be deserialized, iterated and understood), you’ll also want to provide developers with quick references as to what happened with the call, including the use of status codes. And in the case of a failure, you will want to provide descriptive error messages that tell the client not just what went wrong, but how to fix it.

Plan Ahead for your API Documentation

When you are planning your API, you should know how you are going to maintain your API’s documentation. This is one area you should not underestimate since it has proven to be the crux of usability for most public APIs. While documentation may seem like a quick and easy task, most companies will tell you it is one of their biggest challenges and burdens when it comes to maintaining their API.

Documentation is one of the most important factors in determining an API’s success, as strong, easy-to-understand documentation makes API implementation a breeze, while confusing, out-of-sync, incomplete or convoluted documentation makes for an unwelcome adventure—one that usually leads to frustrated developers utilizing a competitor’s solutions.

The challenge is that not only should your documentation be consistent in its appearance, but also consistent with the functionality of your API and in sync with the latest changes. Your documentation should also be easily understood and written for developers (typically by an experienced documentation team). Until recently, solutions for documentation have included expensive third-party systems, the use of the existing CMS (Content Management System), or even a dedicated CMS based on open source software such as Drupal/WordPress. Unfortunately, while expensive API documentation-specific solutions may provide consistency regarding the look and feel of your API (something harder to maintain with a CMS), they still rely on the manual effort of the developer (if derived from the code) or a documentation team to keep them in sync.

However, with the expansion of open specs such as RAML—and the communities surrounding them—documentation has become much easier. Instead of trying to parse code comments and have inline descriptions written (usually) by developers, the documentation team is still able to provide descriptive documentation in the API spec, and all code parameters/examples are already included, making the transition to documentation a snap. And with the explosion of API documentation software-as-a-service (SaaS) companies that utilize and expand on these specs, creating an effective API portal and documentation has never been easier or less expensive. 

How to Write Good API Documentation

Good documentation should act as both a reference and an educator, letting developers quickly obtain the information they are looking for at a glance, while also reading through the documentation to glean an understanding of how to integrate the resource/method they are looking at.

As such, good documentation should be clear and concise, but also visual, providing the following:

• A clear explanation of what the method/resource does
• Call-outs that share important information with developers, including warnings and errors
• A sample call with the correlating media type body
• A list of parameters used on this resource/method, as well as their types, special formatting, rules and whether or not they are required
• A sample response, including media type body
• Code examples for multiple languages including all necessary code
• (e.g. Curl with PHP, as well as examples for Java, .Net, Ruby, etc.)
• SDK examples (if SDKs are provided) showing how to access the resource/method utilizing the SDK for their language
• Interactive experiences to try/test API calls (API Console, API Notebook)
• Frequently asked questions/scenarios with code examples
• Links to additional resources (other examples, blogs, etc.)
• A comments section where users can share/discuss code
• Other support resources (forums, contact forms, etc.)

API Documentation Tools

One of the key benefits to Spec-Driven Development is that instead of having to rely on costly and complex vendors—or trying to build an ad-hoc API documentation solution out of a CMS like WordPress or Drupal—specs like RAML, Swagger and API Blueprint have strong open source communities surrounding them that offer pre-built documentation tools you can use. Each offers its own unique toolset, but in this piece, we’ll  focus on the tools available from the RAML community. The RAML community has already put together parsers for several different languages including Java, Ruby, PHP and Node, as well as full scripts to manage API documentation while providing interactive environments such as the API Console and API Notebook. These tools help you provide documentation as shown in the ReadMe.io, Constant Contact and Twilio examples above with little to no work on your part (other than the installation and, of course, defining your RAML). You can find a number of tools here which can be downloaded freely.

As companies recognize the rising value of APIs they are starting to develop hundreds of APIs. The ability able to appropriately publish them in such a manner that the consuming developer can find, research and understand them easily is going to be a key aspect that will make or break your entire API program. Good documentation is a key part of that.

For more information about how MuleSoft can help you manage the entire API lifecycle, including documentation, take a look at our ebook on Managing the Full API Lifecycle. And for more detail on creating great API documentation, check out Undisturbed REST: A Guide to Designing the Perfect API.