API documentation from technical writer’s perspective – part 1

I would like to share my experience in writing API documentation with you. Probably, many of you are wondering what this mysterious API is and what it is used for. Well, there are different types of API, however, in this article I want to focus only on a Web API.

I came across an API for the first time when I started my short adventure in frontend development and learning JavaScript some time ago. Later, when I joined Craftware as a technical writer, I was assigned to the project where I had an opportunity to co-create API documentation with a solution architect.

You’re probably wondering why this is a task for a technical writer and not an architect or developer? It’s a way to effectively support a project team, whose members can focus on other activities, such as writing a code or improving its quality at the same time.

Let me start by explaining what this seemingly familiar acronym stands for. An API stands for an application programming interface. It can be described as a kind of middleware. It uses a certain set of rules and protocols by which two or more applications or programs can communicate to exchange data. I’m guessing this still doesn’t tell you anything.

Let me use an interesting analogy that I have come across recently. Imagine you are in a restaurant and want to order a meal. You read the menu. Next, the waiter takes your order and passes it to the chef, who prepares the meal. When your dish is ready, the chef gives it to the waiter, and the waiter brings it to your table.

You could say that an API plays the role of a waiter. As a user or an application, you send a query, which is placing an order. The waiter representing an API takes your order and sends it to a chef, that is, a server. In response, a server takes the appropriate action and, through an API (that is, a waiter), sends its response back. In other words, an API is a messenger that receives a query, translates it, and returns the right answer.

Source: What is API ? – DEV Community

You’d be surprised how often you use different APIs without realizing it at all. You do it when you access a website in your browser, publish a post on your social media profile, log in to your bank, or manage your shopping list in an online store.

We already know what an API is and how it works. The next question is: who should read API documentation and why is it necessary?

There is a growing number of cloud-based applications as well as applications that support mobile device users. To exchange data efficiently, service providers use APIs. This allows them to deliver services and software of better quality to their end users. By using APIs that someone has previously designed, service providers do not have to develop their product from scratch and can offer additional functionalities to their customers.

The increased demand for APIs entails the need to provide appropriate documentation that accurately describes their functionalities. Providing it is well-prepared, it ensures a positive perception of a product by a customer, helps build trust among potential business partners, and enhances user experience.

As for who API documentation is intended for, it is primarily aimed at stakeholders and decision-makers in a company, as well as developers.

For stakeholders and decision-makers, such documentation can be useful in assessing the business value of a given API through sample use cases that can illustrate why they should use that particular API in their product. Also, they can find it helpful in assessing the usefulness of a given product to achieve their business goals.

For developers, API documentation is the main source of information on how to communicate with a given API. When using it, a developer should easily find information about the authorization and authentication protocols that expose a given API endpoint (which is usually expressed as a URL) and sample scenarios illustrating common use cases.