Tips for documenting APIs

First, let’s start with a funny example; “If APIs are eating the world, recipe as API documentation, and we as Chefs, always try to offer wonderful dishes to the customers”. I hope now you got my point. As technical writers, our job is more or less similar to chefs, they always try to provide us best food.? Even we work hard to write the best API documentation, which should be easy to read, informative, and succinct. With the help of our API documentation, developers can cook up something wonderful.

Today in this article, I am going to explain easy tips to write the best API documentation;

1. First help yourself when you code:

Always remember one thing; a good design decision always makes it easy to document your APIs. You should be consistent and stick with existing standards to document the items only once.

For example, if you are working with HTTP codes, try not to bend the meanings (avoid giving your meaning), and adding new codes (that’s not our job; let the developers do their job). Try to provide a standard description, like 200 means “OK”, and 404 means “NOT FOUND”.

2. Document from a user’s perspective:

Before start documenting your API, try to analyze the type of audience, and I think this is one of the crucial parts. For example, you are documenting a payment process, users think in terms of refunds, charges, credit cards, and savings. So make sure that you structure your document in that way.

3. Don’t put URI front and center:

Adding URI is the important thing in your API documentation. As we know that URI provides a mapping between the logic and the HTTP clients. Swagger is a popular and widely used API tool; the major drawback of using Swagger is that it generates documents that are URI-centric.

4. Try to write in writing tool:

?Write the document as much as possible with the help of tools, which are mainly designed for writing purposes only. In that case, I would like to give an example of ASCII DOCTOR, a plain text writing tool for authoring the documentation, e-books, newsletter, blogs, and articles. ASCII DOCTOR comes up with various plugins, which can be used in documentation as per your requirements.

5. Generates the examples automatically and combine them with your explanation:

When you check Spring REST docs, they help users to get the complete information with minimum effort. The Spring REST docs are the combination of handwritten (which is written using ASCII Doctor Tool) and auto-generated snippets.

6. Always plan for the future:

?Make sure that your great ideas get used by developers; good API documentation should always be a part of your effort. Don’t forget “APIs make it possible for people with a great idea to provide a credible service with minimum effort and investment”.

?