What You Need To Know About APIs As A Technical Writer

Table of contents

• What are APIs and why do they exist?
• The different parts of an API
• What does this look like in practice?
• The role of technical writers

What are APIs and why do they exist?

API which is an acronym for Application Programming Interface is used to refer to any software implementation that enables two distinct systems to communicate with each other. In modern software development most of this communication is done over HTTP.

APIs can be used in different circumstances with the popular one being enabling developers to introduce functionalities provided by a different system into their own. For example, a developer building an e-commerce website might connect to a third-party system for payment processing functionalities. So instead of building it out themselves, they can connect to the third-party payment provider using APIs.

These days you will also find applications split into separate components and reconnected using APIs, for example, the user interface or frontend of a software application can be made to connect to the backend of the same application through APIs. This has some benefits such as the backend and frontend development team being able to work independently leading to an efficient development process. All they have to do is agree on the structure of the API ahead of development.

The different parts of an API

Before we take a look at the role of a technical writer in relation to APIs, it's important to first look at the different parts that make up an API.

There are 4 key parts of an API you need to know:

• The endpoint/URL: Most APIs work over the HTTP protocol and as part of the protocol you need a URL. Whenever you type in a URL or click on a link to view a page in your browser, you make an HTTP request, and it's no different from the URL used in most APIs. URLs act as roads leading to specific data being sent back to you. APIs leverage this to define the data you will like to request. For example, schools.com/student might return the list of students whereas schools.com/teachers will return the list of teachers.
• HTTP methods/verbs: The communication that happens over APIs goes beyond just getting data. You can also choose to send, update or delete data. HTTP verbs define the kind of request you will like to perform. The 4 popular operations you can perform or HTTP verbs are:
  • GET: To get data from a server or application you will use the GET method. This is what you perform every time you type in a URL and it's the simplest form of an API request.
  • POST: This is used when sending data to a server or application. There are also different ways to define this data ie: JSON or Form Body
  • PUT/PATCH: The PATCH verb is used when updating parts of a data set. PUT is reserved for replacing the entire data set with a new one.
  • Delete: As can be inferred from the name the DELETE method is used when deleting any piece of data.
• The headers: In situations where you want to define how your API request is handled or you simply what to pass some metadata to the server you will pass this information as a header. For example, if you want to get your response back as JSON you can specify this in the header.
• Request body: This is the data you send to the server in the case of a POST, PUT, and PATCH request.
• Response Body: What you get back when you make an API request is known as the response body.

What does this look like in practice?

There is a chance you went through the last section of this article thinking well what does this look like? How do you even use this? It's important to note that the components of an HTTP-based API are more of a specification or directive that defines what APIs should have.

In practice, you will need to use a tool that allows you to define all these components when making an API request. One of such tools is Postman [→]. So for example a third-party platform like Sendgrid [↗] provides developers with APIs for sending out emails. In this case, Sendgrid will have to define what you need to send in terms of URL, HTTP method, and request body and you will put this into Postman to make that API call. Also, Sendgrid will provide you with a sample Response Body so you know what to expect as a response when an email is sent successfully or if it fails.

The role of technical writers

Continuing from our Sendgrid example above, someone needs to document the URL, HTTP method, and request body required to make an API call, as well as what to expect as a response when an API request is made and this is the job of a technical writer.

So knowing what makes up an API helps a technical writer gather, test and document everything a developer will require to make an API request.

Here is another article you might like 😊 Who is a software technical writer? (Q&A)