Do you know what an API is? Have you ever used one? If you answered ‘yes’ to one or both questions, congratulations! You might know how helpful APIs are and how easy they make our lives. If you answered ‘no’ to both questions, don’t worry. I am sure you have used an API without knowing you used one.
According to Tom Johnson, in his course Documenting APIs: A Guide for Technical Writers and Engineers, “In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information.“
One classic analogy about an API is the example of a restaurant. You don’t order your food directly to the kitchen at a restaurant. You usually wait for the waitress to take your order, and the waitress passes the order to the kitchen. In the same way, when your food is ready, the waitress delivers your food from the kitchen to your table.
In this example, the waitress is the API, the kitchen is the server, and your order is the request of a resource.
Now that you know what an API is, imagine the following scenario: you are new to your company and have joined a team in charge of documenting all your company’s APIs. That sounds challenging if you are not a developer, and sometimes, even for a developer, documenting is a pain point.
Why is it important to document an API? A well-documented API makes the work more accessible for the development team and anyone directly working with the API, such as Project Managers, Technical Writers, Scrum Masters, or the final users or consumers of the API.
But what would you do if you had no experience documenting an API? What if you need help figuring out how to start?
How to Start?
Documenting an API thinking as a developer but writing considering a broader audience that might include different roles in your company helps to create a friendlier document that covers all your developer’s necessities but helps the rest of the company understand what your API does and how it works.
Some aspects you can consider starting documenting an API are the following:
-
- What does the API do? It is essential to describe the API’s purpose and provide enough information to the user what the API is intended for.
-
- How can I use the API? Explaining to the user how to use the API makes the implementation easier.
-
- What does the API require? APIs often require a payload or parameters to perform a specific action; if it is not necessary, explaining that to the user is helpful.
-
- What will the API return? Once you explain how to use it, putting one example of the expected response helps the user validate if the API was implemented correctly.
-
- How can I use the API? Explaining to the user how to use the API makes the implementation easier.
-
- Who will use the API? This might be a tricky question; the intention is to explain if the API is for internal users only or if it will be used by external people. This is important sometimes; you can omit certain sensible information if the API is used by external users, and sometimes, you need to expand certain information to make everything easier for those external users.
-
- Error messages. Listing the error messages, their code numbers, descriptions, and solutions help the users when implementing and testing the API.
What is mentioned are a few things that are essential when documenting an API, but open communication with your development team to establish what is essential and helpful to document. Constant feedback from your team will enhance the documentation.
Now that you know what to document, you can focus on how to document. The first step in documenting is to know if your company has an official API template; if the company does not, you can create your own template.
Creating a new template sounds complicated, but at this point, you are free to choose the style and format that best fits you and your company. One recommended action is to ask your developers for their favorite API documentation and use that as the base structure of your documentation because, most of the time, what they like is different from the format but the content and the information provided to them.
Documenting APIs is not impossible, but it requires patience and feedback. A clear document explaining how your API and its components work adds extra value to the API and the company, saving time and money for the API consumers and the company, as well as saving in support resources.
Documenting APIs is a necessary task that can be managed easily. It might be challenging initially, but once your first API is documented, it will serve as your baseline for documenting the rest.
