Web API Documentation Best Practices

Twilio API logo

This guest post comes from Peter Gruenbaum, founder of SDK Bridge. He has worked as a programmer/writer to describe technologies as diverse as the Tablet PC, mobile phones, and social networking.

The number of Web APIs is growing rapidly (there are over 2,000 APIs in the ProgrammableWeb directory), especially with the popularity of Software as a Service. Because Web APIs are still fairly new, the quality and format of their Documentation varies a great deal.

Good documentation is important in encouraging and keeping developers interested in your Platform as well as reducing support costs. Ideally, documentation should cover four areas, as shown in the figure above: overview, getting started, Sample Code, and references. In addition, this article describes best practices specifically for Web API documentation.

Auto-generate Documentation

In order to minimize the amount of work in writing API documentation, it's useful to see how much of the documentation you can create automatically. In the case of SOAP-based APIs, you can take the information in the WSDL and use it to generate documentation pages. Some platforms, such as the Windows Communication Foundation can automatically generate help pages for its REST services.

Keep in mind that auto-generated documentation is just a starting point. You will still need descriptions of all of the elements, as well as overview material.

Include Sample Code

More than anything, developers like to have sample code that they can learn with and start as a base for their own work. One of Web APIs strengths is that they are independent of platform and programming language. Unfortunately, this results in extra work when creating documentation. You should be able to make API calls in Python, Ruby, Java, C#, PHP, and so on. Do you need to create sample code for all of those languages? That may not be practical. Instead, find out which languages are most used by your customers and focus on those.

Show Example Requests and Responses

In addition to sample code, having HTTP, XML, and JSON samples of your request and response is important. However, samples only are not sufficient. In addition, you need a description that explains the purpose of the call and you need a table that explains each element. We recommend a table with columns for Name, Type, Description, and Remarks.

Although the Type column provides most of the information you need regarding format, the remarks section may need to specify further. If an XML element is a date, you should specify the format of the date. If it's a time, then you need to specify its time-zone.

Explain Authentication and Error Handling

Authentication is often required for Web APIs, so you will need to document how to get credentials and how those credentials are passed to the Web server. You may need step-by-step instructions on how to obtain API keys. Sample code is often useful showing developers how the keys work.

You'll need to explain how errors are handled as well. For example, an HTTP call may request data using unauthorized credentials, or it may request an action using data that does not exist. Right now there is no standard way to pass error information back, so developers need to understand how you are passing back error information, why an error occurs, and how to fix the problem.

Finally, remember that Web APIs are built on top of HTTP, which contains its own data. So you may have HTTP-related information that requires documentation as well. This can include caching, content type, and status codes.

Examples to Look At

If you talk to people in the Web API industry, one example often comes up as documentation that's done well. That's Twilio, which delivers cloud-based telephony and has excellent documentation.

What have they done right? First, they've got all of the pieces that a developer could ask for: tutorials, sample code, overviews, references, and an error and warning dictionary. Their reference material is well-organized, breaking information down into the Base URI, a table of properties, and HTTP Methods (GET, POST, PUT, and DELETE, each with XML examples and description). In addition, they've got nice formatting that matches the look and feel of their overall website, and they have a good navigation system.

TwitterIf you don't have the time and resources to create documentation as polished as Twilio's, you can put together a Wiki fairly easily. This is what Twitter has done. The Wiki-style documentation is organized into simple lists with information on getting started, a FAQ, and reference material. Each reference contains a URL, a list of supported formats, a list of supported HTTP methods, and a sample response.

Web APIs are fairly new, and best practices for their documentation are still evolving. In addition to following good practices for general API documentation, follow the above guidelines when creating documentation for your Web API.

For more, read Gruenbaum's full article on web API documentation.

Disclosure: SDK Bridge is a sponsor of ProgrammableWeb.

Be sure to read the next Best Practices article: API Anti-Patterns: How to Avoid Common REST Mistakes