API documentation - a few tips that will help you write it well

The APIs importance for a business strategy that I mentioned in a short introduction doesn’t only come down to the commercial side of the project's success. Nowadays, especially after the Cambridge Analytica scandal, people care more about their data security, so protecting that data and ensuring a high level of security also has to be considered during the API development. A few days ago, Instagram ended cooperation with it’s advertising partner, Hack3r, because of the fact that Hack3r used Instagram’s API to collect users’ data. There is always a possibility to prevent such data leaks that can be harmful to your business and you should strive to ensure the highest software development quality but also take care of the API documentation. 

What is API documentation?

Before we dive into writing the API documentation, let’s focus on its definition. I know that when something has “documentation” in its name, we tend to relate it with some boring and unnecessary stuff or even bureaucracy. Quite the opposite - the fact is that the API is as good as its documentation so polishing it up is always worth it. The API documentation is a precise reference that contains information about how to integrate with an API.  Documentation provides an easier connection with your API and better developer experience as a result. 

How to write API documentation - best practices 

Writing detailed documentation may take a lot of time and you can’t depreciate it. In this article, I won’t show you the only ideal way to do it. My goal is to present good practices and point out some most important elements you should stay focused on when writing good API documentation. 

Remember about the structure

Just like it was in high school when writing essays, here the structure also has significant importance. There are a few main points that your API documentation should include and here are some of them:

• Introduction - here you inform the user what your API is all about. May sound simple but trust me, for some it can be one of the most troublesome parts of the whole writing process. When you spend hours developing your API it can be difficult to simply put the main idea of your project and figure out what can be incomprehensible for other users. 
• Authentication - here you just present the authentication schemes. Of course, there are lots of different types of authentication, one of the most popular and the easiest to implement is the HTTP Basic Authentication. Why your API docs should include it? Because it gives the users some background of your project and if you forget about it they can just reject using it at the very beginning. 
• Errors - simple error messages just inform the users when they make some mistakes in connection with the API.
• Endpoints and available parameters - endpoints show you the way to access the resource and the one resource may have a few different endpoints. What’s more, you should remember that endpoints show only the end path (without the complete resource URL). Here you should also describe the four types of available parameters (header, path, query, and request body parameters). 
• Examples - to provide a better understanding of your documentation you should present lots of examples that can give the user a point of reference and place your API in a wider context. 
• Limitations - you can rate down the overall rate limit that clients are allowed to send. If it is exceeded, they will have to struggle with throttling, that is to say, the processing is going to slow down. 

Think about the audience

You’ll always create better documentation when you define the persons that are going to read it and implement it. The fact is that we can distinguish two different “personas” for your API documentation. First of all, you should have in mind the users - software developers that are going to work with your API. They like to have everything clear so they can implement your API quickly and effectively. Add some examples, show how your API works when its implemented. It gives an additional context to the software engineer and helps to avoid any doubts that would probably arise. Take a look at Twilio docs, they are fueled with different examples and resources that give a wider understanding of the API. 

Secondly you should think about the decision makers, that is to say, CTOs or PMs. They have a great technical background but try not to use some buzzwords that may be meaningless for them. Remember - they won’t be directly involved in the API implementation but they are the ones that make decisions. Always try to put things as clear and simple as possible. 

Think about it during software development

That’s also a very important step you should take to fully enjoy the benefits of well-written API documentation. If you’ve encountered some bugs during the development process, or your team discovered something during the API testing, write down, how you managed to fix it. Find time to discuss your docs with other members of the team, not involved in your project and necessarily software developers. That will help you figure out if your documentation is clear and comprehensible.

Use API documentation tools 

Writing API documentation may take a lot of time and not everyone is able to devote his efforts to do it. Fortunately, there are tools that can facilitate this work and help create your docs almost at a stroke. Tools like Postman or Swagger, of course, offer much more functionalities but preparing API documentation is one of their most important features. 

• Postman - this tool automatically generates sample requests, headers and other metadata and also generated code snippets in the most popular programming languages. 
• Swagger - well-known thanks to the OpenAPI Specification, named Swagger Specification in the past - that’s the world’s standard for defining RESTful interfaces. 

What’s more, not only developers and testers should use them, also Project Managers can gain some benefits from working with Postman or Swagger. 

Is it worth to write API documentation? 

Well-prepared API documentation means better developer experience. If people enjoy your API they will use it more often, awareness of your services is going to increase. And what’s more, good documentation saves your time and protects the developers from frustration - if they find answers for all of their doubts in your docs, they won’t need to contact your staff. 

If I had to find the disadvantages of writing the API documentation I could point out only the fact that it takes a lot of time to prepare it. If you also find it as the only drawback, treat it as an investment - good documentation will allow reducing the number of unnecessary questions that would have to be answered by your customer support team. That is why it is definitely worth spending time improving it!