Posted 54 months ago on 4/27/2010 and updated 10/9/2010
The number of Web APIs is growing rapidly, especially with the increasing 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 for Web APIs because experimentation is more difficult than with local APIs. Because Web APIs are language-neutral, you may need to write sample code in a variety of different languages. Be sure to cover authentication, error handling, and HTTP information.
The number of Application Programming Interfaces for the Web (Web APIs) is growing dramatically. According to John Musser of ProgrammableWeb, the number of new public Web APIs in 2008 and 2009 were over double the number of APIs created in the prior seven years combined. (See Open APIs: State of the Market.) Software as a Service (SaaS) is becoming a very popular business model, and SaaS companies are quickly finding that their larger customers want to be able use their services directly from their own systems. This means that SaaS companies need to have a public API that their customers can call.
Web APIs contain calls that one computer makes to another using the HTTP protocol, where data is returned instead of HTML. Web APIs have many uses. For example, if you are an individual and you want to sell something on eBay, you typically would use the eBay website to put in the information. However, if you are a business that sells items on eBay, then you'll want to coordinate your eBay transactions with your own internal systems to keep track of inventory, budget, etc. With Web APIs, you can expand your internal system so that it takes the information that you've entered and then it makes Web API calls to eBay directly. Through these calls, it can create an eBay listing, check its status, get information for mailing labels when an item is won, etc. This greatly simplifies your business process.
When a Web API call is made, structured data in the form of text is passed from client to server, and other structured text data is returned. Both the structure and the meaning of the data need to be documented in order for developers to use the Web API.
Because Web APIs are fairly new, there is no consistent way that they are being documented. Ted Neward, a consultant specializing in high-scale enterprise systems, compares the culture to the Wild West. But as the industry matures, the hope is that its documentation will become more standardized.
This article discusses Web API documentation and how it compares to local API documentation.
Note: I use the term "local API" to describe the typical kind of API that existed before the Web. Technically, these APIs can be Remote Procedure Calls and therefore they are not local, and technically Web APIs can be called on a server that's the same system as the client, and therefore they are local. However, in most instances, Web APIs, which use standard protocols such as HTTP, are used remotely and other APIs are used locally.
The Importance of Web API Documentation
If local API documentation is not that good, then developers often just experiment until they figure out how it works. However, experimentation with Web APIs is more difficult because you are often working with a live system. For example, if you are trying to figure out Twitter APIs, you don't want to send out actual tweets to your followers as part of your experimentation, so that means you are going to have to set up another Twitter ID just for your development work.
There are other ways that experimentation on a live system can be problematic. For example, you may have a quota on how many times you can make a call, or you might be paying a fee each time you make a call. Also, you might want information about specific conditions, such as how the API responds when the server is under heavy use. That's difficult to emulate when experimenting. The better the documentation, the less experimentation needs to be done.
Types of Web APIs
There are numerous types of Web APIs. Some are for consumer-facing businesses, such as eBay or Twitter. Others are for business-to-business applications, such as SalesForce.com. Some APIs are read-only, such as Quova's API, which returns geo-location information given an IP address. Many others allow you to send information as well as receive it, such as Twilio's call to send an SMS text message. All these factors affect documentation.
The largest factor is whether the API is based on REST or SOAP. SOAP has a definition format (Web Services Description Language, or WSDL) that provides a scaffolding for documentation, whereas REST does not. According to Eugene Osovetsky of WebServius, there is a strong industry trend for public APIs away from SOAP and towards REST.
Autogeneration of 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. (See http://msdn.microsoft.com/en-us/library/ee230442(VS.100).aspx.)
Keep in mind that autogenerated documentation is just a starting point. You will still need descriptions of all of the elements, as well as overview material.
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.
HTTP, XML, and JSON
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.
For example, you might have the following XML element returned as part of a REST API.
Your reference material should have a table that describes each of these elements. You have two options for structuring the information: one is to have one large table that describes every element in the response; the other is to have a table for each complex element. If you have one large table, then you cannot have element names used for different purposes when contained in different elements. (For example, you cannot have a Name element that means a person's name when contained within a Person element, and also have a Name element that means a company's name when contained within a Company element.)
Below is an example of a table that describes the Location element only.
The element that contains the Location element would have a row where the Type column contains a link to this table.
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. When specifying parameters for the request, you may also need to specify extra information about format. For example, if a parameter is a string, are there any characters that it cannot contain? Are there limitations on its length?
If you have a long remark, you may want to refer to it briefly in the table, but describe it in detail in a special Remarks section.
Authentication, Error Handling, and HTTP Documentation
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. In general, you can have errors returned as part of your response (for example, you can have an element named error in your XML), or you can use HTTP response codes to flag errors. In either case, they should be part of your documentation, explaining 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. You can find their documentation at http://www.twilio.com/docs/index.
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.
If 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, and you can see their documentation at http://apiwiki.twitter.com/. 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 these guidelines when creating documentation for your Web API.
Autogenerate documentation if you can, but remember that it's only a starting point.
Create sample code for the languages that your customers use most.
Write reference material that covers element names, types, descriptions, and remarks.
I enjoyed reading this article especially the tips for clarifying API docs "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. When specifying parameters for the request, you may also need to specify extra information about format. For example, if a parameter is a string, are there any characters that it cannot contain? Are there limitations on its length?"
These tips are IMHO relevant for all APIs not just Web. Thanks for taking the time to compile this resource.