API Provider for API Consumer: What to Have on Your Documentation Page

26 July 2017 |

What to Have on Your Documentation Page

As soon as APIs grew into a big business and an economy sprung up around them, documentation became a part of the game. Its importance cannot be understated, as the information it should provide may affect a vendor’s reputation greatly. Documentation can either win an API provider an army of happy API consumers, or become a disaster scaring developers off and leaving providers to look disreputable.

To understand what features would be vital for their documentation, API providers should focus on the audience. All in all, the circle of potential visitors usually comprises the following important users:

  • developers looking to get started
  • those debugging issues in an existing client
  • C-level execs evaluating competing APIs
  • Product Managers puzzling out if the API can work for this or that

With the users mentioned above in mind, a pretty long list of features that API providers should consider including in their documentation can be made. Among them are those that can be regarded as basic ones and those that are rather optional, though desirable.

Structure Points

While there is no standard of what an API documentation should look like, a few units, namely overview, getting started and description, can considerably ease users’ interaction with it.

A perfect API documentation is an extremely understandable one, which implies that a general overview is a must. Here API providers can explain why and how one would use their API and provide some use cases to emphasize its wide applicability.

Clearly not all the developers visiting the documentation page will be familiar with the API, so the getting started section should not be neglected. Programmers will indeed appreciate tutorials and any information on what is necessary to begin consuming the API.

The description part makes up the informational core that people will come to the page for. Thus, it is highly important to pay attention to, the more details, the better. The following tips can be applied to ensure the information is presented in the most favorable way possible:

  • document each API call separately, with parameters and their values explained (see Context.IO)
  • provide examples of each call being made accompanied with details about the requests and responses (GitHub)
  • make it easy to find what is needed by adopting a menu of links (Stripe)
  • explain and exemplify request headers, API responses and error codes just as GitHub does. It is very helpful for newcomers trying to understand how an API call’s behavior can change based on certain HTTP request headers.
  • provide developers with an ability to make live calls right from the documentation page (3scale and API2Cart)
  • create clear tutorials for such complex issues as authentication. These will be much looked up by visitors having no previous experience with the resource you work with every day (Facebook).
  • illustrate the best of your API by providing code samples in the most popular programming languages such as PHP, C#, Java, Go, Python, Ruby, Swift, etc. (see the top of Mailgun)

Other Points

Apart from the particulars mentioned above, there are at least 5 non-structural enhancements worth being considered. To make the API documentation as user-friendly as possible, API providers can take such suggestions into account:

  • do not make descriptions too sophisticated because not all the visitors are going to be developers, and even those who know how to code may turn out to be unfamiliar with the domain and jargon of the API. Documentation is intended to be clearly informative for anyone interested, so it is a good practice to add links to definitions and explanations.
  • let developers improve the content by making open-source contributions just as Parse does
  • if possible, allow spreadsheet export in CSV, Excel or Google Spreadsheet format (some API consumers prefer working with CSV representations of APIs)
  • provide instant help if needed (e.g. add a “support” button similarly to Context.IO)
  • make the text readable, copyable and embeddable (large and clear fonts such as Open Sans or Helvetica for non-code writing and Monaco or Consolas for programme instructions; and maybe a “copy” button)

Conclusions

The audience is the key to determining what an API documentation page should look like. It never hurts to ask for feedback and suggestions, for your users will often know best what would have made the experience even more informative and enjoyable. Meanwhile, the “dos” mentioned in the article make an excellent foundation for what API consumers visiting the documentation page will certainly like.