🧠 API Endpoints Explained
🧠 API Endpoints Explained
Knowledge Series #50: Everything you need to know about API endpoints. What they are, how they work and why they’re important
The Knowledge Series is available for paid subscribers. Get full ongoing access to 50+ explainers and tutorials to grow your technical knowledge at work. New guides added every month.
Hi everyone 👋,
Welcome to the 50th edition of the Knowledge Series!
For folks who are completely new to the Department of Product, the Knowledge Series is a collection of technical explainers for product managers, designers and tech professionals designed to plug any gaps in their technical knowledge - along with practical, hands-on AI tutorials on relevant topics.
Paid subscribers get full access to the series - with new topics added every month. And if you’re interested, you can upgrade to receive them.
Anyway, onto today’s topic: API endpoints.
If you’ve ever worked with engineering teams on integrating with third party APIs or building your own APIs, you’ll likely have worked with endpoints. But some of the terminology surrounding endpoints can be super confusing at times. Plus, the emergence of GraphQL has further complicated the picture.
In this edition, we’ll cover everything you need to know about API endpoints so that the next time you’re working on something API related you’re super confident about all of the terminology used. And as always - we’ll dig into some practical, real world examples from top tech companies to help bring things to life, too.
Coming up:
What is an API endpoint?
How you can hit, expose, invoke, query and call endpoints
How different types of endpoints endpoints are used in products - examples from ElevenLabs, Shippo, Intercom and Spotify
What about GraphQL? The differences between REST and GraphQL endpoints explained
What is an API endpoint exactly?
Put simply, an endpoint is just a location.
And in the context of APIs, the location is a URL which can be accessed by clients who want to use that API.
We’ll take a look at some more detailed examples in second, but for now, here’s an example of an endpoint used in the logistics company Shippo’s API:
When you make an API ‘call’, you’re making a request to this specific URL. And for Shippo API users, this means they’re able to use this endpoint to do things like:
Create a label
Track a shipment
Generate a QR code
In Shippo’s API documentation, it explains to users how the endpoint should be used:
To create a Shipment object, call the shipment endpoint https://api.goshippo.com/shipments/.
This means that developers will send their requests to this URL to create a shipment. The request would contain relevant information about the shipment including things like customer name, street, city, parcel dimensions etc - and once the endpoint is correctly “called” with this information, the API would respond with the response outlined in the API documentation.
“Calling” an API simply means sending a request to the URL provided in the API documentation, but this is where things often get a little more confusing - because engineering teams often have different names for doing similar things in relation to API requests.
Let’s explore some of them.
How you can hit, expose, invoke, query and call endpoints
I remember the first time I worked with APIs and someone on my team mentioned “exposing” and hitting an endpoint. I nodded along without really knowing what he was talking about and then made it back to my desk to quickly Google more information about endpoints.
Sometimes the language surrounding a concept can be more complicated to understand than the concept itself - and once I knew more about endpoints, I figured this was the case here, too.
The phrases "hit," "expose," "invoke," "query," and "call" are often used interchangeably when discussing API endpoints. However, they each have slightly different connotations and contexts.
Let's break down each term: