Conceptual Topics Technical Writers Must Grasp For Effective API Documentation

Overview

One of the things API technical writers must keep in mind when writing API Documentation about a product or service is that users must be able to apply effectively and massively experiment with the information related to the API obtained from the docs. This can only be possible if the API documentation has good conceptual topics - some piece of information also known as the user guide.
In this article, I will be pointing out certain conceptual Topics every technical writer has to include in API documentation.

Prerequisite

• A basic knowledge of APIs

• A good understanding of API documentation is a plus

Understanding Conceptual Topics in API Documentation

Definition

Conceptual topics are what make up the API Documentation, making it easier for users to navigate through the docs more easily and experiment effectively with the API.

Examples of Conceptual Topics in API Documentation

The following are commonly used conceptual topics used in API documentation:

• API product overview

• Getting started

• Authentication and authorization requirements

• Status and error codes

• Rate limiting and thresholds

• Quick reference guide

• API best practices

API Product Overview

This is where a writer talks about the main story of the API. Here are four things you should note when writing a product overview

1. What is it all about?
2. What it does?
3. Who is it for?
4. Why should I use it as a user?

Keep in mind that there are thousands of APIs. If people are browsing your API, their first and most pressing question is, what information does it provide?

To tell your product’s story, consider identifying a market need that your product solves one of the main reasons startups fail is their inability to solve a market problem.

Getting Started

This Section is almost the same as a typical Hello World tutorial in a developer documentation platform, but an API is involved in this case. As an API writer, your purpose and goal in this section is to provide end users with a basic use case of the API to produce the simplest outcome possible. So you must allow a new user to have some success with your product, even if the success is small, like getting a one-line value back from an API call. Here are the following topics you can write about in this section:

1. Signing up for an account
2. Getting API keys
3. Making a request
4. Evaluating the response

Authentication and authorization

Before users make requests with your API, they’ll usually need to register for an API key or learn other ways to authenticate, and authorize their requests.

Definition

First, let’s define the key terms:
Authentication: Refers to proving correct identity.

Authorization: Refers to allowing a certain action.

Differences between Authentication and Authorization

An API might authenticate you, but not authorize you to make a certain request. In Authentication, it doesn’t know who you are, thereby, you have to provide an API Key. While in authorization, it knows who you are, but you have to perform a certain action. However, in API documentation, for privacy and security reasons, you don’t need to explain how your authentication works in detail to outside users. In fact, not explaining the internal details of your authentication process is probably a best practice as it would make it harder for hackers to abuse the API.

However, you do need to explain some necessary information such as:

• How to get API keys

• How to authenticate requests

• Error messages related to invalid authentication

• Sensitivity around authentication information

• Token expiration times

When API requests are authenticated, it helps to prevent malicious users from getting other user-specific data and it also helps to boost a revenue model for companies.
Finally, you could track who is using your API, or what endpoints are most used just by authentication.

If you have public and private keys, you should explain where each key should be used, and note that private keys should not be shared.

API status and error codes:

Most APIs should have a general page listing responses and error codes across the entire API. A standalone page listing the status codes (rather than including these status codes with each endpoint) allows you to expand on each code with more detail without crowding the other documentation. It also reduces redundancy and the sense of information overload.
Status and error codes can be particularly helpful when it comes to troubleshooting. As such, you can think of these error codes as complementary to a section on troubleshooting. for example, whether the request was successful (200), resulted in a server error (500), or had authorization issues (403).

API rate limiting and thresholds:

Rate limits determine how frequently you can call a particular endpoint. Companies with APIs boost their revenue when they charge for access to their API, which is why they offer low and high usage often making the low usage options free so that developers can explore and experiment with the API.

API quick reference:

The quick reference guide helps users get a glimpse of the system as a whole, often by providing a list of the API’s endpoints. Whether for end-user documentation or developer documentation, the quick reference guide provides a 1-2-page guide that provides a summary of the core tasks and features in the system. End-to-end Users can also get a gist of what is going on in the system, all of which are tasks and a quick summary of the API functionalities.

API Best Practices

API best practices can refer to any general advice your product team wants to communicate to developers about working with the API. They can necessarily be tips about fault tolerance - how it can be managed, and what type of specific requests should be used to produce the best results from the API.

Conclusion

To write better, and an effective API documentation about a product and service, the conceptual topics outlined above must be required in your documentation. Yes! They are what provide a critical context for understanding and using the API beyond just the reference documentation - users can grasp the functionality and the purpose of the API, enabling them to effectively apply it in their products. If you have any questions regarding this article, feel free to ask in the comment section. Toodles and good luck!