How to Read and Understand API Documentation

Although you might not know it, you’ve probably already used an API today.

Have you logged into a website using your Gmail or Facebook account? Have you purchased something with PayPal?

Both examples include APIs.

APIs are programs that allow software to connect with one another and exchange data. They’re the corridor information travels through.

Given their complexity, API documentation is crucial to understanding how an API works. Without it, you’re essentially poking around in the dark.

Consequently, we’ve prepared this article to outline the basics of API documentation and teach you how to read and understand these documents.

Why Should You Learn to Read API Documentation

It’s easy to regard API documentation as developer-exclusive content. It’s even in the name—API stands for application programming interface.

However, API documentation can also be helpful for non-technical employees. Think about it: who makes business decisions? Who approves new software purchases?

Product managers are frequently the decision-makers on incorporating APIs into their software, as they’re the most knowledgeable about the product and best suited to make such business decisions.

So, how should a product manager judge an API? They could ask their technical staff to explain it, but it’d be much simpler if they could read the API documentation themselves.

Songtham Tung, a Technical Manager at MasterCard, explains the concept well:

If API documentation is well-written, product managers can understand it independently without contacting technical support to translate. You can read our 6 tips for writing great API documentation!

There’s no need to read code, but a product manager should grasp an API’s functionalities and realize its value.

Generally speaking, APIs offer the following features:

These are all worthwhile business applications. For example, imagine your company has brick-and-mortar locations; wouldn’t a Google Maps incorporation improve your website?

Furthermore, if you’re selling anything, you’ll need to share data with a payment processor to receive your customer’s credit card information—a necessity for most companies.

As such, APIs often provide opportunities for business growth, and product managers can quickly discover these benefits by combing through the documentation.

For example, here, the New York Road Runners utilized a Twitter API to advertise the New York City Marathon:

With these embedded tweets, the NYRR provided promotional content readers could emotionally connect to, and subsequently garnered interest in their event.

However, this is only possible with an API.

By reading API documentation, product managers can identify such opportunities and leverage the API’s capabilities for their own business objectives.

However, there’s another business benefit to API documentation: you can understand their security standards.

This should be a top priority, as software that lacks security can cause significant setbacks.

Look at what happened with Venmo:

A researcher accessed multi-million monetary transactions, including names and transaction descriptions.

There was no hacking involved or slip-ups from Venmo’s side; the data was simply sitting in plain view as part of the company’s API.

You don’t want your data to be similarly compromised, so reading the security measures in the API documentation is a good idea.

Then you’ll know how robust their safeguards are and how protected your information will be.

Laurence Pitt, the Director of Products at Searchlight Cyber, recommends looking out for the following:

Make sure that the API traffic is encrypted. Then use some form of authentication to allow access. Basic authentication would likely be enough, but if the data is sensitive, consider having the authentication backed by certificates.

If you notice these measures in the API documentation, the software is probably secure enough to trust.

On the other hand, if there aren’t any documented security features, this is a significant red flag; the API might not be reliable. In such a situation, it’s better to look for other services.

However, the first step to making such decisions is reading and understanding the API documentation. Without that ability, you’d be left in the dark.

How to Understand API Documentation

API documentation is written primarily for developers since they have the most contact with APIs. Consequently, these texts usually contain technical jargon and aren’t easy to navigate.

In fact, only about half of companies accommodate non-technical audiences. Look at the statistics:

Just under half of organizations don’t have an API strategy for non-technical users. Furthermore, even the half with such a strategy likely requires some basic API knowledge.

The following sections will walk you through API documentation so that you can gain a good grasp of any company’s API specifications.

Familiarize Yourself With API Terms

The first step to understanding API documentation is understanding API terms. These are new, technical expressions you might not know, yet they’re essential for API operations.

Endpoint is a good example.

An API is a bridge between two software applications, sending requests between them and thus allowing them to exchange data.

However, these requests must be sent to a particular location—an endpoint.

Reading API documentation is essential, as it contains a list of available endpoints. You’ll learn the API’s connectivity capabilities.

Here’s a visual illustration:

API documentation will reveal accessible endpoints, listing where you can send your requests. This is invaluable information, as it facilitates using the API.

Here's a good read recommendation: API Documentation: Improving the API Developer Experience

Regarding what types of API requests to send, this is usually also provided in the documentation. The text should outline everything the API expects from the request.

Most APIs nowadays use standardized OpenAPI/Swagger specifications, displayed below:

These standardized requests are most frequently used and are the basis for typical API operations. In fact, some documentation tools even auto-generate these specifications.

For example, here’s how that works with Archbee:

Source: Archbee on YouTube

This feature allows popular API requests to be easily incorporated into your documentation in just a few clicks.

After sending an API request, the software might accept it, but there are other possible responses.

These responses are expressed through response codes, each with its own meaning.

Here’s an overview of possible responses:

While memorizing every response code is unnecessary, it’s worth familiarizing yourself with the most common ones, such as 200, 400, 404, etc.

These three phrases (endpoints, API requests, response codes) are the essential building blocks of a functional API. After mastering these terms, you’ll easily understand API documentation.

Start by Reading the API Overview

Once you’ve mastered the standard API terms, you can then dive into API documentation. However, before reading every article, it’s best to start with the API overview.

The overview section introduces the API’s capabilities, documenting what precisely the API does and how to use it best.

You’ll gain a general understanding of its functionality by looking it over.

For example, here’s an overview of Shutterstock’s API:

This text details precisely what the API offers, so you know what you can accomplish by utilizing it.

Furthermore, the overview is broken down into sub-sections, outlined on the left-hand side in a table of contents. Depending on what interests you most, you can jump to the relevant category.

Shutterstock only has one API and hosts only one overview page. However, larger companies might offer multiple APIs (and multiple API overviews) based on how many services they provide.

That’s how Mapbox operates, for example.

Take a look:

Since the API has four services, there are also four overview pages.

When reading such comprehensive documentation, remember to read all the overview pages. You don’t want to miss any services, and it’s always better to know the whole picture.

Some API overviews also include video introductions. Instead of reading text, you can watch a video, which might be the better medium for retaining information.

The animated explanations and dynamic format will probably stick in your mind longer than static text.

For instance, Google shot an explanatory video for their Maps Geocoding API.

Have a look:

It’s not a bad idea to watch these types of videos, as you’re likely to learn more quickly by watching instead of reading.

If the API overview does include such media, take advantage of it—you’ll familiarize yourself with the API more quickly.

Read recommendation before you move on to the next chapter: Visuals in Technical Documentation: A Guide

Take a Look at the API Reference

If the API overview is an introduction to the API, the API reference is a deep-dive look at its functions.

This guide lists every API method, providing a detailed directory of the software’s capabilities.

By examining the API reference, you’ll see if the API can perform the exact action you need, and if it can, it’ll offer concrete, detailed information on how to do so.

MailChimp’s API reference is a good example.

Take a look:

This screenshot illustrates the operations associated with Authorized Apps and Automations. Furthermore, each request can be expanded to include more details.

Here’s the extended version of the first GET request:

With this expanded view, you’ll access additional data on query parameters with an accompanying code sample.

Although this much detail probably isn’t necessary for you, you can remember this page to show your developers later.

And this is just one example; the same comprehensive information is provided for every API functionality.

Some API references are even more extensive than this. For instance, Meta’s API reference is highly exhaustive, listing requirements and fields for its API functions.

Have a look at the requirements for the Album node:

This table outlines every requirement necessary for creating an Album, depending on the node type the Album is on.

Again, depending on your needs, this might be too technical, but your developers will certainly benefit from this page.

Some API references are written for such a complex service that there’s a dedicated long-form page for each functionality.

That’s how YouTube’s iframe Embeds are documented, for example.

Take a look:

The right-hand side hosts an extensive table of contents, each subheading containing information.

Just by glancing at this organization, you’ll discover you can control playback, retrieve video and playlist information, and add or remove an event listener.

With such a comprehensive reference, you’ll learn everything you need about the API for iframe Embeds.

Read Through the Provided Tutorials

Now that you know if the API can perform the functions you need, it’s time to look at what precisely these operations look like.

The easiest method for this is reading through a tutorial. That way, you’ll get a fleshed-out preview of the API.

Tutorials walk you through using the API, a thorough yet straightforward guide on utilizing a particular functionality. However, they’re typically more detailed than a simple API reference.

For example, here’s one of Spotify’s API tutorials:

The tutorial provides step-by-step instructions on how to set up a Spotify Web API, guiding the reader through the exact workflow.

When reading through API tutorials, ensure they follow the same logical, clear-cut structure as Spotify’s API.

For such a tutorial to be effective, the order of operations should be obvious, so you can easily follow the instructions.

Furthermore, a good API tutorial also includes media such as screenshots and screen recordings. With these visuals, verifying you’re performing the correct steps is much easier.

Just take a look at Twitter’s API tutorials:

The written instructions are further explained with helpful screenshots, so the user knows exactly what to expect when following the tutorial.

When reading API documentation, look for such visuals, as they’re a sign of a well-composed tutorial.

However, your developers will want more than visuals; high-quality API tutorials also include code samples.

After all, such snippets are the easiest method for developers to understand the API’s inner workings.

Here’s a great example of a code-supplemented tutorial:

There are step-by-step instructions, and each section is complemented by a code sample so that developers know exactly what they’re dealing with.

If the tutorials you’re reading include such code snippets, this is a surefire indicator of high-quality API documentation.

Conclusion

APIs are extremely helpful, sophisticated software. They’re one of the chief reasons behind today’s interconnectivity and are utilized by most users daily.

However, using them without first reading the documentation is like trying to find a needle in a haystack. And by the way, Archbee can really help you with documenting your APIs.

Despite their usefulness, they’re also highly complex and sometimes difficult to understand.

Consequently, reading and understanding the documentation is vital to making intelligent business decisions.

Once you’re fluent in API documentation and learn how to read and understand API documentation, both senior management and the developer team will thank you for it—you’ll be a huge asset to the firm’s success.

‍

FAQ