Documentation
Last modified on Thu 23 Sep 2021

An API without accompanying documentation practically doesn't even exist. Furthermore, without good, thorough documentation, no API can be good either. As the developer behind an API, you are naturally familiar with what you've created and how to use it. However, your clients are not. Documentation exists to transfer that knowledge to clients.

Documentation writing requires thinking about what the API client needs to set up their environment, what they're able to do with the API, what to send in requests and which response scenarios to expect. All of this naturally requires providing lots of information and structuring it in a comprehensible way.

Writing isn't easy and developers tasked with writing documentation sometimes do a poor job. Poorly-written documentation necessitates further communication and explanations from the API developer — imagine then what would happen if you had to explain your API to a thousand confused clients. Therefore, to save time in the long run, you have to invest enough time to write proper documentation from the start.

Essentials

The following checklist contains documentation essentials. This is not an exhaustive list — APIs always have specifics which cannot be included in such lists and you should document them as well. A good rule of thumb is, if someone would ask about it, it should be documented.

Bonus points:

Hall of fame

Everything written about documentation practices in the preceding paragraphs sets a basis for writing API documentation. But it's just that — a basis. Real-world APIs are big and complex and to write comprehensible documentation for them means to consider many aspects not pointed out here. Instead of trying to put everything into words, here are some examples of API documentation that prove that it's possible to manage complexity and present it in an understandable and user-friendly way to the clients.

Automating documentation

Documentation writing is laborious. Most of it has to be done by hand — nothing can replace that — but some things can be automated. One of the things we can automate are example requests and responses.

Dox

Infinum's very own gem that does the majority of work in regards to API documentation for the developer. It's super easy to set up and with just a couple of changes to your existing request specs, you get an updated API documentation after the specs finish running. Check the dox documentation by following this link.