🧠 APIs explained for product managers and non-engineers

Knowledge Series #5 Making sense of REST, endpoints, documentation and more

🔒The Knowledge Series is a series of easy to read guides designed to help you plug the gaps in your tech knowledge so that you feel more confident when chatting to colleagues. Clearly explained in plain English. One topic at a time.

 If you’re a free subscriber and you’d like to upgrade to receive them you can do so below. Or you can find out more about paid access here.

---

Hi product people 👋,

When Reddit, Twitter / X and Stack Overflow decided to charge for access to their APIs, this caused a huge backlash from consumers and introduced major disruption for third party apps alike. Some apps even had to shut down as a result (RIP Apollo). As Large Language Models (LLMs) increasingly feed off the information freely available to them by open APIs, it’s inevitable that companies with open APIs hit back.

“Community platforms that fuel LLMs absolutely should be compensated for their contributions so that companies like us can reinvest back into our communities to continue to make them thrive,” - Stack Overflow CEO Chandrasekar. 

Similarly, Spotify’s API documentation now explicitly tells users that its music can’t be used to train machine learning AI models.

But while we’ve previously covered the topic of API product strategy development, in this edition of the Knowledge Series we’ll take a step back and instead answer the more fundamental question: what is an API?

Coming up:

1. 🧠 What are APIs and why should you care?

2. 🧑‍🏫 Top terminology - a deep dive into the 10 most important API terms to know including:

   1. requests and responses, REST, HTTP methods, endpoints, API documentation, API calls, payloads, response codes, headers, and authentication.

3. 📚Tools, resources, videos and further reading

You can use this as a reference guide for the next time you’re integrating with an API, reading API documentation or thinking about building your own APIs.

Let’s dig in. 

---

The Knowledge Series

What are APIs and why should you care?

API stands for ‘application programming interface’ but this really doesn’t mean anything on its own. For non-technical readers, the best way to think about an API is to focus on the ‘interface’ part of this definition. 

Just as you’d interact with a UI (user interface) in traditional products, there is still interaction taking place but instead of that happening between a user and the product, it’s between two applications or systems instead.

Application 1 can interact with application 2 in any number of meaningful ways, so long as both systems recognise each other. This is set out in API documentation - more on that later.

But before we delve too deeply into some of the terminology, the key thing to understand here is that at its heart, an API is simply a way for 2 applications to communicate with each other. This communication typically has some form of utility which benefits a user of the API - otherwise what’s the point in using the API in the first place?

The benefits and business cases for using APIs

APIs open up unlimited opportunities for the creation of valuable products. As we’ve noted, if it weren’t for open APIs, LLMs wouldn’t exist. 

The business case for APIs

Businesses typically utilise APIs in 3 different ways:

1. Integrating with third party APIs

2. Building their own APIs for internal use

3. Building and exposing their own APIs to customers

The most value-adding of these for product-led tech companies is integrating with third party APIs and building and exposing customer-facing APIs. Whilst building APIs for internal use is a critical part of service-oriented architecture and inter-operatibility in general, unless those APIs are later ‘productized’ to be customer-facing, there isn’t a strong business case for the development of them, aside from the day to day necessity of using them.

Before we dig into some useful terminology, let’s explore these use cases in a little more detail.

1. Integrating with third party APIs

Connecting with other companies’ APIs allows you and your product to fast track adding features, functionality and tools that would otherwise take you and your team years to build.

Chances are that you / your team have worked on integrating with an API at some point. Typically you’ll talk through a feature set and your engineering team will know of an API that will handle the task you need to do via a third party.

Most products today utilise integrations with APIs in one way or another. Here’s a few examples of open APIs that are widely used by millions of websites around the world today:

• Crunchbase’s API allows businesses to find information about startups and tech companies 

• Spotify’s API allows users to find out information about songs, artists, tracks and playlist and embed them into 

• Mailchimp’s API allows users to subscribe, unsubscribe, add, delete users and send email campaigns.

For a handy catalogue of open APIs that you can use when you’re considering developing your own product, check out the Rapid API directory.

These are examples of how you can utilise single integrations with third party APIs, but the real value of APIs comes in the combination of multiple APIs to create unique value propositions for customers.

A transport company like Uber or Lyft for example, could use multiple APIs. Other products would equally be impacted if access to APIs was suddenly switched off.

Products that would die if APIs didn’t exist

1. Ecommerce marketplaces like eBay, Amazon, Alibaba etc use APIs for inventory management and shipping. Without APIs shipments wouldn’t be tracked correctly with carriers and payments wouldn’t process.

2. Payment gateways like Stripe integrate with products to facilitate payments via API integrations. Online payments would be impossible without API integrations.

3. Travel aggregators like Expedia, Kayak, Skyscanner etc all gather data from travel providers from various APIs. Without access, aggregators would lose their ability to gather this information and provide accurate pricing.

Pretty much any product that doesn’t own its entire tech stack - or doesn’t require anything from third party services - would be put out of business if APIs didn’t exist. And even then, APIs power internal products and services, too.

But luckily for us, this isn’t the case since many companies choose to expose and productize their own APIs.

2. Exposing and productizing your own APIs

Should you expose your own APIs? Well, it depends entirely on what your product is / does and what your business goals are. If creating your own APIs means you’re going to get X number of new clients which means you’ll achieve your quarterly growth targets then it’s worth considering. If it’s a colleague’s pet project that demonstrates no clear business value then don’t.

For some businesses, APIs are the business; the value the company offers to customers could not exist without APIs since the value is delivered through APIs. 

Some examples of this include Twilio which allows companies to send text messages to customers based on user actions.

Similarly, no-code API tools like Zapier wouldn’t exist without APIs, either.

Our Knowledge Series guide on developing an API product strategy explores this further and can help if you’re planning to.

But that’s enough on the strategic considerations of API development. Let’s instead focus on the terminology that’s useful to know.

Key API terminology to know

I remember when I first joined Ebay’s shipping team. One of the first things my boss did was ask me to familiarise myself with the company’s API documentation - including third party API docs. In the shipping and logistics teams, so much of the value you offer to customers is linked deeply with APIs: 

• Tracking shipments with tracking events

• Sending manifest details of items shipped

• Inventory and order management 

All of this required deep knowledge of not just our own APIs but of shipping providers, too. UPS, DHL, FedEx, USPS, Royal Mail, etc - there are literally hundreds of different shipping and logistics companies! I knew a little about APIs and was completely overwhelmed by it all. I eventually learned about the value of API aggregation services which allow you to integrate into a single API and offloads the work to others, but it really was challenging.

If you’ve never worked with APIs or you find yourself suddenly burdened with the task of exploring API integrations, hopefully this terminology deep dive will help.

I’ve put together a list of the top 10 things I think are useful to know about APIs based on my own experience. And here they are…

The 10 most important things to know about APIs

1. Requests and responses

2. REST

3. HTTP methods

4. Endpoints

5. API documentation

6. API calls

7. Payloads

8. Response codes

9. Headers

10. Authentication

Let’s explore each of these in more detail.

Requests and responses

In our guide on front end technologies, we explained that the web itself is built upon the request and response model. 

Take a look at your browser to prove it. HTTPS is a more secure version of HTTP where information is encrypted.

Your browser makes HTTP requests to a website’s server every time a new page is loaded and it is something called HTTP methods which are used to tell the server what to do. These methods are also used by APIs. More on these later.

At a very basic level, APIs work using ‘requests’ and ‘responses’. 

I request something in a specific format as outlined in the API documentation and the API responds with something in return.

For example, using the Spotify API I can request a list of songs from an album.

In order to do that, the following needs to take place:

1. I send a request to the Spotify API

2. As part of my request I tell Spotify which album I want to retrieve a list of songs for using an ID e.g. Blackout by Britney Spears (a classic) has a unique ID

3. Spotify responds with a list of songs from the Britney Blackout album in a language called ‘JSON’

The API documentation will specify what the request should be and what you can expect in the response.

This is a super simple example, but other APIs work in the same way:

• In Stripe’s API, I can make a request which contains information about a customer payment and get a response about whether or not it’s successful

• In Shopify’s API, I can make a request about a product and get the product information such as price, images and category back in a response

• In Reddit’s API, I can make a request about a subreddit topic and get information about that subreddit topic in the response

But you’re not limited to just ‘getting’ stuff from APIs. And this is where an understanding of HTTP methods comes in handy.

HTTP methods

When working with APIs, HTTP methods are used to request information. The methods are the ways you do things with APIs. 

Think about how you would interact with your dog as a weird, but potentially helpful analogy. You would say ‘FETCH’ if you wanted your dog to get you something, ‘SIT’ if you wanted your dog to sit and ‘PAW’ if you wanted your dog to raise its paw. 

The way we work with HTTP methods is similar in that they describe various ways in which you can get things done.

The most commonly used HTTP methods are: 

• POST 

• GET

• PUT

• PATCH

• DELETE

And here’s how some of these they work:

GET

• Used to read / retrieve a representation of a resource.

• When you perform the GET method, the response contains the information you requested.

• GET requests are only used to read data and not change it. This means they’re considered safe.

POST

• Used to create new resources.

• For example, if we wanted to create a new text message using the Twilio API, we would use the POST method since this is how you create new resources (where the resource is the text message).

PUT

• Used to update / replace data.

• For example, updating a user’s email address.

DELETE

• Self explanatory. Used to delete data.

There are others but we’re only going to focus on these since these are the most common. If you know these, you know enough. You’l notice we made a few references to ‘resources’ in those descriptions and so you might be wondering ‘what’s a resource?’. 

Good question.

REST

Resources are part of RESTful API architecture. You’ve no doubt heard the term REST or RESTful throughout your career but you might not have any idea what it actually means. There are plenty of people who could spend hours deep diving into RESTful architecture, the pros and cons of it and whether GraphQL is a better architectural approach.

For this, we’ll cover the basics.

A technical definition

REST stands for representational state transfer and whilst that sounds fairly scary, it is used to describe a set of architectural principles and characteristics outlined in a document in the early 2000s by a guy called Roy Fielding. 

The document lays out a series of principles which should be followed in order to create a RESTful API.

A non-technical definition

Think of REST as a set of members club rules. The owner of the club is saying, “hey everyone, look, if you want to be part of this REST club, you’re going to have to follow a certain set of rules”. 

What are the rules? Here’s a summary of the rules or characteristics of a REST API:

The difference between Rest and GraphQL

And before we move on, it’s also worth mentioning a popular alternative to RESTful APIs which is becoming increasingly popular - GraphQL.

Teams don’t have to choose one over the other, and it typically depends on what kind of product you’re building - and the needs of that particular product. 

Shopify has both a REST API and a GraphQL API, for example. And in my own experience, GraphQL can be used in situations where it’s more important for engineers to be able to identify a extremely specific resource or objects since it’s less resource intensive.

With GraphQL, you make one API call to a single endpoint which contains the specific query you need to identify a resource. In a similar way to how SQL works but with APIs.

Here’s a quick comparison of the two, with some examples of the companies who use each:

You’ll notice the comparison includes references to endpoints. And we’ll explore those next. 

Endpoints

An endpoint is a place or a location.

It’s a connection point which accepts requests to access resources on an API. An endpoint needs to be ‘exposed’ so that it can be called. Think of it as an email address that can be contacted or a telephone number that can be called to get some information.

The response you get is predictable.

If I want to report a crime I call the police at 911. The response should be ‘hello 911 what’s your emergency’ - or something similar.

If I have a query about my payslip I’d email my HR department and I’d expect to get a response in a timely manner about my payslip.

If I want to call my partner I call their number. The response here might be a little less predictable but we’ll move swiftly on.

In this example from the Spotify API, you can see:

• The HTTP method e.g. GET (which is used for reading and retrieving information)

• The endpoint e.g. https://api.spotify.com/v1/albums/{id}

This means if we want to retrieve information about an album, we send a request to the endpoint or URL location (https://api.spotify.com/v1/albums/{id}) which includes the ID of the album.

Spotify responds with a representation of the album.

A real world Britney example

Going back to the Britney example, if we want to use the Spotify API to get a representation of the Britney Blackout album, we would send the album ID to Spotify and in return we’d receive a representation of it.

Here’s the request we’d send:

And here’s the response we get back:

This isn’t the full response (I’ve shortened it for ease), but you can see the response contains information like:

• The album name

• The number of tracks

• Album artwork 

• Release date

And in order to get all of this information from the API we send a request to the endpoint. 

How the term ‘endpoint’ is used

• Hit – endpoints can be ‘hit which means we reach an endpoint to request a resource.

• Exposed – endpoints can also be ‘exposed’ which will allow resources to be retrieved by others e.g. ‘we can expose an endpoint which will allow an image of a barcode to be retrieved’.

• Call – ‘if we call the artists endpoint on Spotify we’ll retrieve a list of artists’.

API documentation

The primary purpose of documentation is to lay down the rules of the ‘contract’ and to help engineering teams understand what functionality is available by using different API calls.

API documentation will typically include many of the following:

• Authentication instructions – how you connect with the API

• API endpoints – what endpoints are available

• Resources – what resources are available for you to access. For example in the Spotify API, they allow to you access Playlists, Albums, Artists, Songs

• Request format – how an HTTP request to the API should be formatted

• Response format – how an HTTP response is formatted when you receive the response

• Response codes – what response codes are included in the response (we’ll talk about these later).

If you’re new to working with APIs, it’s worth familiarising yourself with your own API docs (if you have any) and also with docs from leading tech companies. Leaders in API documentation would include Stripe, Twilio, Github, Shopify and OpenAI.

API calls

We refer to the requests to APIs as API calls. Not telephone calls but exchanges of information.

API calls involve hitting an endpoint with the expectation that the API will respond with the information you need.

In the Spotify example, you call the albums endpoint with a specific album ID and Spotify responds with information about that album.

Payloads

You’ll sometimes hear engineers refer to the ‘payload’. This is just a fancy way of talking about the response from an API.

It refers specifically to the meaningful information in a given set of data. Not everything in an APIs response is something we care about, so the term payload is used to distinguish between the stuff we’re interested in and the stuff we’re not.

E.g. ‘If you check the payload from the Spotify API you can see the length of the track is 3 minutes’

Response codes

At the start, we reiterated that the web is built using the request / response model - and that APIs use this model too.

A fundamental part of that model is the response codes that are returned every time a request is made. 

When an API request is made, it will return a response - and along with it a code. The codes are helpful ways for engineers to debug any problems, and devops engineers often use third party tools to monitor how frequently specific response codes occur as a way of managing code quality and bugs.

There are plenty of others so this list is by no means exhaustive but it’s enough to give you a foundational knowledge of the most frequent so that when people talk about ‘a 500’ you’ll know it’s a problem with the server.

Headers

When you send a request to an API, your request will include something called headers. The response from an API will also contain headers.

Headers are additional useful bits of information which are sent and received along with your HTTP methods. Some headers are mandatory and some are very rarely used.

Response codes are included in headers and from a non-engineering / devops perspective you’d rarely need to know more about headers than the fact they contain response codes.

Authentication

In the same way as you would authenticate yourself when logging into your email or other secure account using a username and password, you need to do something similar for accessing APIs.

If you have an external facing API which needs to be accessed by clients, they will typically be issued with a security token and credentials which they will need to use to access your API.

If you have a product with an external API, your third parties will be given a username, password and access token to access your API. Often, a token can be provided in the sandbox environment to allow their developers to play with.

Still reading?

Well done if you’ve made it this far! As I said in the beginning, this guide is designed to be used as a reference if you ever find yourself working with an API in the future. You might be familiar with some parts of API development and less so with others.

Now that we’ve covered the most important practical parts of working with APIs, you should now feel more confident when chatting to colleagues or external partners about your API strategy.

You deserve a break, so we’ll leave it there for now. And if you fancy it, why not ask the Spotify API to play your favourite album at the same time? No, it doesn’t have to be Britney.

Tools, resources and further reading

• RapidAPI - a directory of free and paid for APIs

• Firefox API glossary of terms - the folks at Firefox write some excellent guides

• An Introduction to REST, by Google

• Why REST is so popular, by ByteByteGo

• Apigee, a nice tool for APIs

• PAW, a great tool for use on the Mac

---

Thanks for reading this Knowledge Series and if you found it helpful, hit the like button - I’d really appreciate it! ❤️