What do Technical Writers Document in an API?

You may be wondering, “What do technical writers document in an API?” This chapter will clear all your confusion. It’s perfectly fine if you do not know any of these terms. After all, you are here to learn. So, let’s dive in and explore what Technical Writers document in the world of APIs.

Imagine you’re in a new city, and you want to find the best places to eat, shop, and sightsee. You could wander around aimlessly, but you’re more likely to have a successful trip if you have a map or guidebook.

APIs are like new cities. They’re full of possibilities, but they can be confusing to navigate if you don’t know where to start. That’s where technical writers come in. They create documentation that helps developers understand how to use APIs.

Let’s consider this: Your project team asks you to document a new endpoint that they have created. They may refer to each endpoint as an API, but essentially they are asking you to create a reference API document. Here are some of the things that you will include in your reference API document:

• Endpoints: These are the URLs that developers use to interact with the API.
• Methods: These are the actions that can be performed on an endpoint. For example, a GET method can be used to retrieve data, while a POST method can be used to create new data.
• Parameters: These are the values that are passed to the API when a request is made. For example, a GET request might require a parameter that specifies the ID of the data that you want to retrieve.
• Requests and their bodies: These are the data that is sent by an API in request.
• Responses and their bodies: These are the data that is returned by the API in response to a request.
• Examples: These are code samples that show how to use the API.
• Error messages: These are the messages that are returned by the API when an error occurs.
• Authentication: This is the process of verifying the identity of a developer before they are allowed to use the API.
• Rate limits: These are restrictions on the number of requests that can be made to the API in a given period of time.

Technical writers also document other aspects of APIs, such as the overall architecture, the security features, and the limitations. They strive to create documentation that is clear, concise, and accurate.

Here are some additional examples of what you might document in an API:

• The required permissions for each method.
• The expected format of the data that is passed to and returned by the API.
• The error codes that can be returned by the API and their meanings.
• The best practices for using the API.
• The limitations of the API.

So, just make sure you know what we document, how we do it; it’s something we will talk about later in the course. In essence, Technical Writers craft an essential guide that empowers everyone to understand, navigate, and make the most of the API world.

Course completed