On the last post, I described what does it mean: good documentation. On this post, I want to expand this subject by focusing on API documentation. In modern web development using such kind of interfaces is a very common activity. Our application can consume some public RESTful API or just specific to this one application. APIs is everywhere on the internet. It can be used be the people on the internet or by our developers. Regardless that, it is definitely worth to prepare clear documentation to save their time.

Three types of documentation

At first, we need to consider how we can prepare such documentation. Depending on our needs we can create documentation in following forms:

• tutorial – step by step instruction to make common tasks
• guide – a story about the system, its use and
• reference – a full list of actions and results

Based on my experience, the best option for API documentation would be a full reference with short general guidance and tutorial for less experienced users. The reference part This form let us provide the most valuable information for developers.

Important features

Looking on above three types of documentation we can consider what is the most important on each of them.

Tutorial

At the beginning, developers who don’t use our API before need a patient guidance. The best method is a manual showing what they should do to start working with API – kind of quick start guide. It should contain a list of technical steps to establish communication. We can use a test data. The main purpose is to give a quick insight into the configuring connection to API.

A good idea is a sample project to start working with API very fast. It can be redundant if we provide some other interactive way to execute requests.

Guide

It is also important to show developers some more general information about API. More experienced developers need a knowledge about:

• authentication
• error codes
• acceptable data formats
• custom headers and status codes
• caching
• rate limiting

Reference

To be sure that documentation would be useful and usable we should ensure that it saves time and effort in the use of specific API. It should:

• provide example request and response data
• allow to execute requests with test data. We can also provide a test server to handle that requests)
• shows examples in different languages (i.e. the 3 most popular)

The main principle

This summary led us to the greatest one. Good documentation should be clear for developers. Easy to search, read, copy and test. This is the most important parts.

The biggest problem

All these rules sound very good. It would be great if we will be able to satisfy all. However, it is very hard. The biggest problem is to keep it up to date, after each change in our API. It requires additional work, but if we want to keep a good quality of this documentation we need to maintain it.

So what can we do? The most accurate answer would be an automation. We can use tools to generate documentation and should only take care about guidance part.

On the next post, I will try to show tools for this purpose.

Good API documentation examples

• https://stripe.com/docs/api – it is definitely my favorite documentation form. It consists all easy searching (it’s one-page site), good guide and examples. Moreover, it is responsive and good looking.

• https://www.twilio.com/docs/api – it provides an additional long description to each API method. It gives a context of use and special cases.

• https://dev.twitter.com/rest/public – clear and useful

• https://developer.github.com/v3/ – it also gives additional notes about methods

• https://documentation.mailgun.com/api-sending.html#examples – the neatest feature is a curl example that every developer can execute on his own

References:
http://blog.parse.com/learn/engineering/designing-great-api-docs/
https://bradfults.com/the-best-api-documentation-b9e46400379a#.q3h63e2mj
http://www.programmableweb.com/news/web-api-documentation-best-practices/2010/08/12

Cover photo