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


Comments (16)


You forgot the most important thing: ACCURACY.

Make sure the documentation is up to date, reflects all available methods, and accurately describes the method calls. Nothing is worse than incomplete or inaccurate documentation.

I would also mention readability as being very important as well.

I have run into tools like that with a number of our clients, and they are extremely helpful. I don't believe they are a complete substitute for documentation, but they can definitely cut down amount of getting started material and sample code that you need to publish.

There is a lot of very useful information in this post, as well as in the other comments. That said, I have found that with the NPR API that if you provide good enough tools in how to navigate the API, the documentation (while still very important) is less used by a considerable margin. We created a tool called the <a href="http://www.npr.org/api/queryGenerator.php" rel="nofollow">Query Generator</a> that is an interface allowing developers to select the items that they want in the query, create the query string, view results, etc. Other organizations like CNet and The New York Times have created similar tools.

Making such tools will lower barriers for use, make the process easier and more pleasant, and will likely result in less active engagement by your team in supporting use of the system. But as @JP suggests, accuracy of the tool is also important, so as the API changes, so should the documentation and the tool.

Just use oData.

[...] And there&#8217;s a really important note too about keeping documentation up to date. It&#8217;s so important that it&#8217;s a matter of life and death (of your API). So, try to stay on top of the docs and read our Web API Documentation Best Practices. [...]

Yes, accuracy and readability are critical. However, for this blog posting, I focused on what's important specifically for Web API Documentation, as opposed to API documentation in general.

[...] around the edges, currently. The API documentation is not complicated, but it&#8217;s missing some key documentation elements, like response examples. The Face Detection API is also very simple, and not a lot of options seem [...]

[...] Web has a nice article called Web API Documentation Best Practices. It brings up several important points about how API developers should document their APIs. [...]

[...] And there’s a really important note too about keeping documentation up to date. It’s so important that it’s a matter of life and death (of your API). So, try to stay on top of the docs and read our Web API Documentation Best Practices. [...]

[...] So what&#8217;s the solution? Many software developers are familiar with the notion of an API, an online webservice that computer programmes can talk to. Services like Facebook publish comprehensive APIs that let third party developers build services on top of the Facebook platform, pulling data from and writing data to it. To make life easier for the developers, API publishers often publish software libraries that make it easy to use the API, or code examples that show how to achieve some of the tasks that can at least get you started with the API (for example, The Six Pillars of Complete Developer Documentation or Web API Documentation Best Practices). [...]

[...] August 20, 2010 by JP &middot; 2 Comment(s)Programmable Web has a nice article called Web API Documentation Best Practices. It brings up several important points about how API developers should document their APIs. [...]

[...] I&#8217;ve been brushing up by re-reading my technical writing course material, learning about web API documentation best practices, API documentation for coders, and studying some of the best examples of technical writing from [...]

[...] 4. Web API Documentation Best Practices by Peter Gruenbaum &#8211; Source: ProgrammableWeb Because Web APIs are still fairly new, the quality and format of their documentation varies a great deal. Find enclosed the details about a good API documentation. [...]


I pay a quick visit every day a few sites and websites to read articles or reviews, except this blog presents feature based writing.