How to Read API Documentation

APIs and product management

Product managers are not engineers. But there is an expectation that product managers are both technical enough to to have conversations with engineers and to articulate those technical concepts to stakeholders.

Most non-technical stakeholders will have little to no understanding of many technical concepts, but of all the different parts of technical product development, it is perhaps APIs that stakeholders will talk about the most.

When was the last time your sales or marketing lead talked about the importance of react components or NoSQL databases? Contrast that with the often frivolous references to APIs and it’s clear that working knowledge of APIs is one of the most critical for product managers.

We’ve previously deep dived quite heavily into the wonderful world of APIs so if you’re looking for a refresh on how APIs work you can check that out here. But in this post, we’re going to focus specifically on one aspect of API-related skill sets in particular: the ability to read and understand API documentation.

Why should I bother learning how to read API documentation?

One of the primary benefits of using APIs is that they allow your product to piggyback off others to add new forms of value to your users. Many products would simply not exist if it weren’t for API integrations.

Imagine a CRM that couldn’t connect to an email provider.

What if Quickbooks wasn’t able to connect to business banking feeds?

Or what about an ecommerce provider that couldn’t provide shipping rates and tracking?

APIs are now an essential part of product development – and your first introduction to APIs as a PM might be an encounter where you’re tasked with exploring a potential API integration or partnership.

I once learned the hard way when I forgot to ask fundamental questions about an API partnership and didn’t fully read the API docs ahead of time. It was only later in the discussions did we realise that the API docs were all in a clunky old SOAP / XML format, which would render the partnership impossible. Not a pleasant experience 🙂

The important bits of API documentation to know about

REST API documentation will typically include a selection of the following:

1. Authentication – instructions on how to connect with the API
2. Resources – what resources are available for you to access. Different APIs will have different resources available to use.
3. Client libraries – packaged ways to integrate with the API via programming languages
4. API endpoints – what endpoints are available for you to use.
5. Request format – requests are sent to APIs and in return they respond with information. The request format specifies how a request to the API should be formatted.
6. Response format – APIs will respond when you send them a request. The response format specifies how an HTTP response is formatted when you receive the response.
7. Response codes – what response codes are included in the response

In order to be able to confidently read API docs, you’ll need to understand what each of these elements actually mean.

Let’s use a real world example to bring this to life.

Example 1 – Shippo

Shippo is a provider of shipping features to ecommerce businesses. This means if you run an ecommerce business and you need to print out labels for your parcels, Shippo will handle that for you, thanks to – you guessed it – API connections with shipping carrier networks like USPS, DHL etc. We’ve chosen Shippo as an example because they have a name which combines shipping and hippos.

Using Shippo and some other products as examples, let’s see if we can understand what each of the core elements of API documentation mean.

Authentication

In order to connect to an API to make use of its functionality, you need to authenticate and prove that you are a user with the correct privileges.

This is done using a token. In the context of Shippo, they make it clear that in order to make live requests i.e. in order to start using the API to print off shipping labels or validate addresses, you must register and authenticate using a production token.

The token is generated based on your user and is then used in each API request you send. If your token expires, your access to the API is restricted or denied.

Resources

REST APIs allow you to access resources. Think of resources as pre-designed bundles of information that are useful to the user of the API and linked to the overall value proposition of the product you’re using.

As a product manager, you may be tasked with exploring the functionality of a particular API and the types of resources that are available to you is a critical part of that analysis.

If you want to use the Shopify API to mark an order as fulfilled, you’d need to ensure the API allows you to do that.

If you plan on using the Mailchimp API to retrieve your latest campaign open stats, you’d need to check if a campaign resource is available.

If you wanted to create a Trello card every time a new customer service issue is raised, a check of the Trello API and the resources available to you would be in order.

For more information on resource-oriented design in REST APIs, check out this handy guide from Google.

Client libraries

One thing you’ll notice when you read API documentation is that there are often examples of different programming languages.

Heading back to our Shippo API, you can see a bunch of different examples of how to get started with their API.

In this example, you can see that Shippo have given us a bunch of different ways to get started, using different programming languages, including:

• Python
• Ruby
• Node.js
• PHP
• Java

These are examples of libraries that have been packaged up to work with specific programming languages; the core functionality of the API remains the same across the different programming languages, but the way in which you interface with the API is slightly different depending on the programming language your product is built in.

For Ruby developers, for example, a common way to access third party apps is through something called a Ruby Gem. A Ruby Gem is a package which contains code and documentation on how to work with the application you’re looking to connect with.

In the context of our Shippo API, the Ruby Gem will allow Ruby developers to interact with the Shippo API from a Ruby-programmed product. The client libraries are designed for your engineers to get a head start in interacting with the API.

As a non-engineer, you don’t need to worry too much about this – the ability to understand the functionality that’s available to you via resources is more important. As is the ability to figure out how to test the API.

And for that, you need to know what endpoints are available.

API endpoints

Third party integration testing will often be completed endpoint by endpoint. What does this mean?

Let’s say you’ve decided to integrate with an API and you want to check that it behaves correctly.

To do that, you’ll at least need 3 things:

1. The documentation to understand what API endpoints are available to you
2. An environment in which to test the API connectivity
3. An understanding of what to send in the request and what to expect back in the response

An endpoint is simply the location to which you are sending your API request. When you send an API request, the request is similar to a sentence, comprised of nouns and verbs.

Imagine asking your dog to fetch the TV remote control (this is an extremely well trained dog).

‘Go fetch the remote control’

would translate to:

GET the RemoteControl

In this example, the method is GET and the resource you want is RemoteControl. The endpoint would be the place you’re sending the request. In this case, the request is sent to your dog. So your dog’s ears would be the location – or the endpoint – that you would send the request to.

Maybe dogs just make this even more confusing, so let’s try with some real examples too.

Example 1 – Mailchimp

This overview explains how the API can be accessed.

You’ll notice that it mentions the ‘Root’ – in this case, the root is just the start of the URL address that you send your API requests to and it includes a unique value depending on the data centre your account uses.

The example they include says:

https://us6.mailchimp.com/account/api/

This means that the endpoints you send your API requests to will start with this but finish with the location included in the endpoint description.

This example should help explain a bit better:

You would send a request to the /reports endpoint and your request would contain a specific campaign_id.

https://us6.mailchimp.com/account/api/reports/{campaign_id}

The endpoint is reports and the reports endpoint expects you to send it a campaign ID so that it knows exactly which campaign you’re referring to.

Example 2 – Spotify

The Spotify API gives you access to a bunch of different resources, mostly related to music and playlist management, as you’d expect.

For endpoints specifically though, you can see here on the Spotify API documentation website that the API gives you access to a bunch of different endpoints.

In this example, we would make a request, or call, the albums endpoint by sending it the unique identifier for an album (the album ID), and in return we would get back information about the album.

As we mentioned, as a non-engineer, it’s often the case that you’ll be involved in testing API integrations with third parties and approaching it endpoint by endpoint means that you’re testing that what you get back in your response is exactly what you’d expect, based on the API documentation.

This can only be done by understanding requests and responses. And we’ll dive into those next.

Request format

Every time you use an API, you’re sending a request to a specific location (and endpoint) and the API responds with a specific response, depending on what you’ve requested.

API documentation will make it clear what the API expects to see in the request.

In this example from Shippo, using the POST method, we can create a new shipment. The documentation outlines what the API expects to receive from you when you send the request to create a new shipment.

If we look at some of the fields, you’ll see that they’re pretty self explanatory.The API splits out required fields and optional fields, with the following marked as required as the rest as optional:

• Address from (required)
• Address to (required)
• Parcels (required)

The request must use the correct format for each of the fields. If not, the API will throw an error. You must also use the correct HTTP method for each request.

HTTP methods used in REST APIs

If all is good, the API will respond with exactly what the documentation expects.

Response format

API documentation that is worth reading will always include solid working examples of what to expect in the response.

If the response you and your team is getting back from an API doesn’t match the API documentation then this should be considered a major red flag.

Sometimes, it’ll be an innocent mismatch between an outdated version of the docs and the API, but other times this can suggest that the API vendor is not maintaining the API specs correctly which will no doubt make life more difficult for you further down the line if you plan on using the APIs for critical parts of your product.

Anyway, back to the response.

As you can see from our friends at Shippo, this is the response they send when you use the PUT method to create a new shipment.

The response includes all the things you might expect, including:

• Confirmation that the shipment has been created with a “Status – success” message
• Information relating to when the shipment was created
• Address information for the recipient

The response will also include details on the response code.

Response codes

Response codes are simply numbers which represent different things which can then be interpreted by engineers.

Here’s a sample of the responses you typically get back from APIs:

GraphQL API docs

So far, we’ve focused exclusively on REST APIs, but over the past few years a new kid on the block has emerged – GraphQL. So before we wrap up, it’s probably worth us taking a look at some of the most important bits to know about how to read GraphQL APIs, too.

What are GraphQL APIs and how are they different to REST?

GraphQL is an emerging technology that uses a different architectural pattern to REST APIs.

Just as SQL allows you to be very specific with what exactly you want to retrieve from a database, GraphQL allows engineers to construct API requests that contain information about exactly what they want to get from the API – as opposed to retrieving the entire resource, as you would with a REST API.

Let’s look at some GraphQL API docs to get a better understanding, shall we?

Example – Shopify GraphQL API docs

In this example, you can see a few things that are worth noting to help understand the difference between REST and GraphQL:

1. Single endpoint – in GraphQL, all requests are sent to a single endpoint and the request itself will be specific about what you’re looking to access
2. Queries – ‘Queries are equivalent to making a GET request in REST’ – with GraphQL, you are querying the API with specific criteria to get back what you want
3. Granularity – note the request here says ‘products(first: 3)’ – allowing the user of the GraphQL API to be incredibly specific about what you want

One of the main differences with GraphQL vs. REST is that with GraphQL you can construct a query that can include information from multiple resources at the same time. This makes queries more efficient than REST APIs since they don’t retrieve all the data you might get from a resource in a REST API; rather, you just get exactly what you asked for.

Summary of the differences between REST and GraphQL

For a deep dive into some of the granularity available when constructing GraphQL queries, check out this handy guide.

Bringing it all together

As we mentioned at the start, of all the different technical concepts that product managers should have working knowledge of, APIs are towards the top of the list.

We often get thrown into the deep end, and for junior product managers in particular, this can be pretty terrifying.

But, with a little hands on experience and working knowledge of the fundamentals of APIs plus the ability to read documentation confidently, you should now be well prepared for the next time a non-technical stakeholder starts chatting APIs with you :).