This question is answered using logic: every developer should document their API well because this documentation is, in fact, the “instruction manual” that other people will use to integrate with it. Ensuring that explanations are simple, direct and clear will make that integration faster, and everything will work better.
The era of connectivity
Internet as we know it has been developed on the foundation of connectivity. It is a space where users of all kinds can connect with each other and benefit from each other, whether it is by sharing a simple conversation or making the most complex economic transaction imaginable.
In this sense, APIs (Application Programming Interface) is the hinges, the connecting threads that make it easier for users to connect to each other without issues and take advantage of mutual benefits.
But for this connection to happen in the simplest, fastest and most efficient way possible, any API worth it’s salt must have good documentation. It must be interactive, show the structure clearly and ensure that developers do not have to waste time doing research or pointless tests.
In this sense, Core’s Team Leader Dani Calle knows what it is all about: documenting an API well “reinforces knowledge management”, but it is important to think about quality and not quantity when doing it. “As one of my first bosses said: If it’s not documented… it means you haven’t done it.”
Clarity, conciseness, and precision
Keeping secrets in this field does not make much sense if you want the API to be used by as many people as possible and in the right way. This means it is important that you take some time to think about how best to structure the content of that documentation.
What you want is to be understood, so cryptic language and mysteries are best left behind. The information that you offer through your API, well-structured and explained, is the key. Other developers who design applications based on it can now do so easily.
“If you want them to use what you are offering, it has to be communicated. One mechanism for this is to have attractive and usable documentation that reflects the state-of-the-art of your APIs and, above all, that these APIs are alive…”, says Dani Calle.
Getting off on the right foot
First of all, you have to define the index, that is, consider how you are going to organise the information, point by point, topic by topic. This index should always be interactive and not too extensive in terms of a number of pages and tabs, to ensure that the user does not get lost.
It is also a good idea to state the programming languages that the interface supports and list all devices and formats that can launch requests to your API.
API functionalities
One of the main points, and something that is essential is that the documentation of your API makes it clear from the beginning what it actually offers. Detailing the functionalities and the specifications of each one, as well as everything it provides to third-party applications, will help other developers understand what your API consists of at a glance and what opportunities it offers.
Always include guides where all information is stated, making sure that both experienced and inexperienced developers can understand it. This way you will expand the range of the audience that might be interested in working with your API.
Use examples
Using examples in the documentation of your API – both to explain all its functionalities and the possible answers as well as showing some more complex functions in detail – allows the user to take more advantage of it without having to invest too much effort.
A dynamic and simple formula for introducing examples in the documentation of your API is to include the occasional tutorial where highlighted functions are explained more in detail, as well as more complex processes.
And, lastly, time is money, so do not forget to add shortcuts that help other developers run quick API test, in particular for everything that is especially relevant and that facilitates learning related to the new environment.