6 Tips for Documenting RESTful APIs

If APIs are eating the world (as InformationWeek suggests), you can think of API documentation as recipes, a crucial part of making your API easy to understand and easy to use. Just as chefs rely on well-written recipes to create wonderful dishes, you need to create API documentation that is informative, succinct, and easy to read so other developers can cook up something wonderful using your APIs.

Andy Wilkinson, Spring IO Platform lead at cloud-native platform company Pivotal, provided great tips in his presentation “Documenting RESTful APIs” at SpringOne2GX in Washington, D.C., last month. Earned through hard-won experience, here are some tips Andy provided to help you create RESTful API documentation your users will love.  

1. Help yourself when you code

Good design decisions make it easier to document your APIs. Be consistent! If you can remain consistent in naming conventions and stick with existing standards for behavior, you’ll have to document an item only once … if at all! For example, for HTTP status codes: don’t bend meanings, don’t add new codes: “Don’t force users to understand your slightly eccentric view of the world.” Don’t go off the beaten path: 200 means OK. 404 means not found.

The same holds true for HTTP verbs: use POST to create, DELETE to delete. These are well-established conventions, violate them at your own risk. One exception: PUT and PATCH. The documentation for these is unclear (good luck with the RFC), and different apps have different interpretations of them. Some APIs make PUT and PATCH synonymous; just be clear on your particular usage. (You can find more info in this StackOverFlow discussion: What is the main difference between PATCH and PUT request?)

2. Document from a user’s perspective

Remember that users come to your APIs with a mental model of the context you are working in. For example, if you are providing a payment processor, users are thinking in terms of charges, refunds, customers, and credit cards. So it makes sense to structure your documentation that way. For example, look at the Stripe API docs. They provide a nice introduction and then group APIs in a logical way. GitHub provides good example of well-organized RESTful API documentation, with groupings like Git Data, Pull Requests, Issues, and Users.

3. Don’t put URIs front and center

Making URIs the most obvious thing in your documentation requires users to figure out mapping between your logic and the HTTP client. Also, many users will hard code the URIs, which will break clients if you use hypermedia controls and then change them. This is the biggest drawback to the oft-used documenting tool Swagger. Swagger is popular because it provides a lot without much effort, but it generates docs that are URI-centric. For example, the vFabric Administration Server REST API documentation was inspired by Swagger. Because the URIs are so prominent and the structure is poor, this documentation may be accurate but it’s not terribly helpful. This is the example Andy provided because he helped create these docs, and learned some hard lessons from the experience.

4. Write in a writing tool

Write as much as possible in a format that’s designed for writing. “Writing documentation in annotations is horrendous,” Andy explained. Consider a tool such as ASCIIDoctor, a plain-text writing format for authoring documentation, notes, books, and also a publication toolchain. There is also a huge ecosystem around ASCIIDoctor, which includes lots of useful plugins.

5. Generate examples automatically and combine them with your explanations

Andy created the Spring REST docs project to help users get the information they need with a minimum of fuss. It combines handwritten documentation written with ASCIIDoctor and auto-generated snippets produced with Spring MVC Test. This combination hits the sweet spot between automation and manually generated information.

6. Plan for the future

Look at the Richardson Maturity Model to determine how RESTful your APIs actually are. Your documentation tools can constrain you if your code is more RESTful (or you plan to make it more RESTful) than your tools allow. Don’t box yourself in. Do you plan to get to level 3 and use hypermedia? Then make sure your tools will support that.

As InfoWeek’s Thomas Claburn explains, “APIs make it possible for a few people with a great idea to offer a credible service worldwide with minimal effort and investment.” To make sure your great ideas get used by other developers, good API documentation should always be a part of your effort.