🧠 Knowledge Series #5: APIs explained
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 👋,
The decisions by major companies including Reddit, Twitter / X and Stack Overflow to charge for access to their APIs 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:
🧠 What are APIs and why should you care?
🧑🏫 Top terminology - a deep dive into the 10 most important API terms to know
📚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.
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:
Integrating with third party APIs
Building their own APIs for internal use
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
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.
Payment gateways like Stripe integrate with products to facilitate payments via API integrations. Online payments would be impossible without API integrations.
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…