Over the last few years we’ve documented a number of REST APIs for clients, so we thought it was high time we shared some of our learnings. In this article, we’ll share some tips on how to tackle REST API documentation and make the output more effective for your developer audience.
The first thing to consider is the layout. Without a doubt, the three‑column layout popularized by Stripe is the way to go (see https://stripe.com/docs/api/node#intro for an example). This layout takes full advantage of today’s widescreen monitors by putting the TOC on the left, content in the middle, and code samples on the right. In fact some implementations even allow you to resize each column and have independent scrolling for each. Note that the code samples are typically presented with a black background, which shows color syntax highlighting better than white, and makes the samples distinguishable from other content.
Interestingly, we’ve found that many clients have chosen to create their own system for developing this layout. But, if you don’t have the means to do so, be sure to check out http://readme.io. They provide cloud-based tools allowing any developer to expose their API in the Stripe-like style.
Another aspect that makes the three‑column layout effective is having the right amount of information – not too much and not too little. The goal is to provide just enough information to get developers going, while avoiding the traditional user manual approach of having “walls and walls” of text, as this will give you the best result. This will provide developers with the information in nice, consumable chunks, without cluttering things up. In addition, it will make the code samples in the third column line up nicely with the content in the second column, making it immediately obvious as to their relationship.
On a similar note, the TOC of a three‑column layout tends to use only three levels of headings. The first level is to categorize information, the second level is for endpoints or objects, and the third is for requests. Keeping things to three levels is another example of keeping things simple. If content can’t be organized into three levels or less, then it should probably be reorganized and further simplified. The type of information found in most REST documentation tends to be communicated best when keeping the header levels limited.
When it comes to REST code samples, we often debate about whether the sample should show tool/platform‑specific examples (e.g. showing how to make a request using CURL) versus just showing the request type and URI. Similarly, it’s also a debate over whether to show header information or not.
Providing platform-specific examples can be useful for the reader. Stripe for example, allows the reader to select the language at run‑time which helps developers consume the API across many popular frameworks. However, be aware that providing code samples for multiple platforms multiplies the authoring effort for each sample, not to mention their maintenance over time.
For most projects we’ve found that providing just the request type and URI along with any JSON or XML payloads is the way to go. It provides a great balance between authoring effort and providing just enough information for the developer. Any additional header information can be documented once in an “overview” section, and the developer can figure things out from there.
Another area to consider is whether a data type (i.e. object) definitions should be documented as part of each resource, or if they should reside in a separate “Objects” section. We prefer the latter because objects and sub objects are often reused across many resources and endpoints, so it makes sense to have them in their own section and then cross referenced where needed.
The Square API documentation is a great example of this (see https://docs.connect.squareup.com/api/connect/v2/#navsection-datatypes). Here, there is a separate “Data Types” section which is referenced from many request parameters and response field descriptions.
The final tip we’d like to pass along is around organization. Sometimes the organization of an API can be surmised from the endpoint URI’s and other times the organization is not so clear. Thus it’s important to work closely with your developers to determine the proper groupings of requests, and to document them accordingly. The key here is to have a really good understanding of the API’s purpose, workflow, and order of operations – something that a technical writer with a programming background will easily be able to handle.
In summary, REST API documentation is becoming increasingly important as the demand for mobile and web apps increases. Using a three‑column layout like Stripe gives the most effective presentation, and avoiding the temptation to flood it with content will ensure that developers get just the right amount of information.