APIs are everywhere. You open an app, you scroll for a bit, you click a few buttons, you write a comment. But have you ever asked yourself how it all works?
The internet is powered by APIs. You just may not realize it.
Code and Data: The Raw Ingredients
To start understanding how APIs work, we need to understand the two fundamental building blocks of any computer system: code and data.
Code is the logic that is written to tell a computer how to act. The data is what the computer acts on.
If you were cooking a dish, the code would be the recipe, and the data would be the ingredients. With certain data and the right code, you can create almost anything.
But instead of focusing on the building blocks, let’s zoom out to get somewhere practical.
Servers, Clients, and APIs: Enter the Restaurant
Have you ever posted something on your phone, but then later pulled it up on your computer? How does this work?
In practice, most applications are split into two distinct parts. The front-end (i.e. “the client”, or what you see on your phone or computer) and the back-end (i.e. “the server”, or where the API runs and the data is stored).
Think of this distinction like a restaurant. The front of house is what you see: the tables, the decorations, the silverware, the wait staff. The back of house (the kitchen) is the back-end: the server (the tech server, not the restaurant server1), the API, the database.
I realize I’ve mentioned the term API without ever defining it. API stands for “Application Programming Interface”, though I don’t think that definition helps explain what it is. The API is the central location for fetching data in a structured way. Bear with me, this will make more sense as we dig in further.
The front-end is the interface. It is the website or app you are able to see when you grab your phone. The back-end is often made up of two parts, the API and the database. The database is where data is stored, while the API is the code and logic that dictates who can access certain pieces of data. Both are critically important.
The distinction between the front-end and back-end is really: where is the code running? On your device (i.e. an app or website) or on a server in a data center (i.e. “the cloud”)2.
The front-end screens are often templates, waiting to be filled with data. When you open the Instagram app, for example, you’ll often see a quick shimmer of templated nothingness before the posts and stories pop up.
In this brief moment, what actually happens? Your app (the client) is reaching out to the Instagram API (the server) to go fetch your data from the database.3 The data is not coming from your phone, it is coming from “the internet”.
While there is front-end code running on your devices, the job of this code is typically to fetch data from the API and display that data in a pretty way to you.
Interacting with the Client: Ordering the Food
Every time you click a button, something happens. What happens is that your app or website (“client”) sends some data to an API (“server”).
When you sit down at a restaurant, you are given a menu. In the same way, an API has a menu of “allowed orders” that the client can make. You can only get certain pieces of data from each API4. For the Instagram API, for example, two items on the menu are Posts and Stories.
The waiter at the restaurant is your app. They are the ones who take your request, and deliver it to the kitchen. The kitchen then cooks the food, hands it back to the waiter, and it is delivered to you.
What can an “order to the kitchen” look like?
You create a new post.
You post a new story on Instagram.
You start building a story and save it to your drafts.
You click on a “like” button. This creates a new Like associated with the post.
You open the app. It immediately loads the last 24 hours of stories posted as well as the last week or so of posts. This used to be simple, but now the algorithms decide what you get to see next as opposed to a chronological list of your friend’s posts, like the good old days of social media.
You send someone a message.
Each click is just another order for your waiter to take to the kitchen.
Not all orders have to be made through a click, however. When you open the Instagram app, it puts in several orders to the kitchen by default (i.e. makes several requests to the Instagram API):
Fetch stories from the last 24 hours sorted by timestamp
Fetch all relevant posts for this user
Fetch all notifications
Fetch all messages
In other words, when you sit down at the table, someone brings you bread, water, and a menu. Not all apps do this, but it is a pretty unpleasant experience to sit down at a table and have to wait for several minutes for the waiter to come by. The good apps will make your experience cozy by default.
The Database: The Storage Fridge
We’ve talked about data, and how it is one of the building blocks of a tech system. Now, let’s introduce the concept of a database.
If data in our metaphor is still the ingredients, then the fridge is the database. It is where the raw ingredients are stored before being ready to be cooked. Before taking orders at the restaurant, we need to make sure the restaurant is ready to be stocked with food.
What is a database? Imagine a large excel workbook, with many spreadsheets in it. Each sheet (i.e. database table) has a structure, and the data can only be structured in that format.
Let’s imagine a simple social media app that just allows you to post ideas and like other ideas. Think the early days of Twitter. The database table structure may look like this:
Users — (id, name, email)
Posts — (id, text, created time, user_id)
Likes — (id, post_id, user_id)
Every piece of data in a database has an identifier (ID) that can link to other pieces of data. For example, a Post has a user_id that references a specific user. If my User account is stored with ID=20, then the app knows that all Post objects that have user_id=20 are made by me. In this way, we don’t have to duplicate data across the tables.
In the same way, when I Like a post, it is stored as an association between my User and the Post (i.e. it uses my user_id and the post_id).
While this is a very simple database structure with just 3 tables, in practice, backend systems often have over 100+ database tables. I would guess that Instagram has more. All of the data is structured according to this table structure, and therefore very easy and predictable to fetch and return to the billions of users.
Relational databases are complicated, but incredibly powerful. Once you realize that clicking a button is just modifying data in a database, it demystifies a lot of the technology that is omnipresent in our lives.
The API: Welcome to the Kitchen
Now back to the kitchen. The kitchen, or the API, is code running on a server. It is always waiting for orders to come in. The kitchen is always open, and always ready to serve you.
Let’s think of a sample order: liking a post on Instagram. While it seems like a very simple order, the kitchen has to do a lot to fulfill it. Let’s break down the steps one by one, both in technical terms (a) and restaurant terms (b).
The Order
Your app (the “client”) makes a request to the Instagram API (the “server”).
The waiter takes your order and delivers it to the kitchen.
Authentication
The API validates that the request is coming from an “authenticated” user. Authenticated is a fancy word for being logged in.
The chef makes sure that the order is coming from a trusted waiter. If an average Joe walked into the kitchen and told the chef to cook them something, they would get kicked out. Not just anyone can make a request. Only authenticated users can make requests5.
Validation
The API validates that the request is made properly, and it can support the request. For example, it looks up the Post to make sure that it exists still and can be liked. It also determines if your user is allowed to like this post (i.e. are you following this user). There is a lot of validation that needs to happen to make sure that people follow the rules of the restaurant.
The chef validates that the order is on the menu, that they have the right ingredients, and that they can cook the order.
Calling the Database
Database Stores
Database Returns
The API calls the Database to save the data. The database can do its own validation before saving, and eventually returns the stored data to the API code, saying: “I saved this data successfully, here is the stored data.”
The chef calls out the order, the staff fetches the ingredients they need to cook the meal from the fridge, and they begin to cook the dish. They give the prepared dish back to the chef.
Format the Data
The API takes the data that was created and turns it into a format that the client is expecting. Most commonly, the data is returned to the client in JSON format6.
The chef plates the dish in an aesthetically pleasing way that is ready to serve.
Returning the Data
The API returns the data to the client.
The waiter picks up the food from the kitchen and brings it to the table.
Side Effects
Sometimes there are side effects to actions. In our example, one side effect would be to notify the User who made the Post that you liked their post. Other side effects could be like sending emails, or updating data elsewhere in the system. There are a lot of connected parts to a software system, and each has a role.
For a restaurant, the side effects aren’t as immediate, but for example, an order could cause the chef to have to go get more ingredients to cook food. Or washing dirty dishes. There are always things that have to happen to keep the kitchen running smoothly, just as there are in software.
And then the kitchen waits for the next order. All of this happens for one request, but a similar process happens each time you scroll or click. Your click is just one order, and the Instagram API processes billions of orders every single day. A pretty efficient kitchen.
There are a few specific types of orders to the kitchen, each of which does something different to the data in the database. The main types of orders are Creating data, Reading existing data, Updating data, and Deleting data (often known as CRUD events, which I understand is a silly name).
If you think about it, almost everything you do online falls into one of these four categories:
Create → I post something on instagram, a Post record gets created in a database
Read → I want to see everyone’s story from the last week. Or I want to see that post that I made a few years ago. These are all reading existing data from the database.
Update → I want to update my caption (some systems allow this, some do not).
Delete7 → I don’t like my post, and I decide to delete it.
Why does this all matter? APIs are everywhere, every app has its own data to store, and everything we do online creates more data.
Even as I sit here typing my article in Substack, my browser is making requests to the Substack API to save my draft.
I hope you learned something reading this post, as I plan to continue this series on how technology works. In future posts, we will build on this foundational understanding to dive deeper into specific parts of tech. There are aspects of APIs that we didn’t cover such as “how does the API know it’s you?” and “What happens when I connect my account to another service?”
The next time you’re scrolling or clicking, think about some of the complex technology systems that exist behind the scenes to power it. Because there’s a kitchen cooking every time you click.
Until next week,
Cory
There is further confusion around the API as the “server” vs. the actual hardware called a “server”. These are both colloquially correct. The API server runs on the hardware server. Confusing, but what isn’t in tech?
A quick aside on data centers, “the cloud”, and how the internet really works. You’ve probably heard data centers, and heard that we have to keep building more of them. A data center is just a massive collection of computers. Some call them “servers”.
These servers are rented out to people to run their code.
In the days of old, people would have to have on-premises servers, meaning they would have to own their own server computers in a server room. Their code would literally be running in their office. While some companies still do this for a number of reasons, the world has changed significantly since 2005, largely going to the “cloud”.
The cloud is a nice marketing buzzword for “renting servers to run your code”.
Most of the internet at this point runs on AWS (Amazon Web Services). Amazon owns a tremendous amount of servers and rents them out to people like me, looking to host an application for cheap.
This infrastructure has been largely commoditized, leading to a tremendous influx of new applications. When you had to buy a server to run your application in 2001, it was much harder to launch an app. In 2025, if I have a new idea and want to put it on the internet, I can just rent space in AWS and start running my code today. While this makes it easy for people to spin up new applications and databases, having to pay rent in the form of hosting costs is rough. But I digress. Back to the article.
Sorry for my crude whiteboard drawings, maybe someday I’ll splurge on an iPad and an Apple Pencil.
This is called an “API schema” or “API spec”, but the terminology is not very important. Just know that an API does not do everything. It can only give you certain pieces of structured data.
This is not the case for all restaurants. Imagine a food truck where you tell the kitchen directly what you want. In the same way, some APIs do not require authentication. Anyone can make a request and get data. For example, Reddit in the old days. These unauthenticated services are getting less and less common.
JSON stands for JavaScript Object Notation. JavaScript is a programming language that gained popularity with the web. When your web browser is running any code, it is almost always JavaScript. How are you able to do things on a website? Someone wrote the JavaScript code to allow you to do it.
In practice, there are very few deletes. Tech companies don’t like deleting your data. Why would they? Data is power. Instead, they usually do what’s called a “soft delete” where they set a field in the database called “Deleted At”. This is a timestamp (i.e. a date and time) that the action happened. Any database records that have their Deleted At field set are considered “deleted”.
When you ask to get all posts, the API will filter out the deleted ones, even though they’re still in the database. So if you delete your post from Instagram, it doesn’t remove the post from the database. In the same way that Snapchats are not actually deleted. They are just not visible to you, the user.