đ§ 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âŠ