Table of Contents

• Intro
• The Restaurant
• The Menu
• Placing the Order
• The Plate Coming Back
• Don't Need to Know How the Kitchen Works
• The Internet Version of the Story
• A Real Example
• Why This Matters
• Different Flavors of APIs
• Where to Go From Here

Intro

If you eavesdrop on a conversation amongst developers, you're bound to hear "API" thrown around. This is the acronym for Application Programming Interface and is one of those phrases that explains nothing the first time you read it.

However, most people don't realize that they already understand APIs. You interact with them in a non-software form your entire life. The tech version is just a copy of something physical and ordinary, something you've used a thousand times without thinking about it.

To explain what an API is, we're going to spend the next part of this blog visualizing that you're in a restaurant.

By the time we walk back out, you'll be able to read most "this app uses an API" sentences and know exactly what's happening underneath. You'll also know what to ask when something doesn't work, which is half the battle of working with APIs.

The Restaurant

Picture yourself walking into a restaurant and sitting down at a table. You're hungry and have a rough idea of what you want already, then a server walks over to you to take your order.

Now, let's notice everything you don't have to do.

You don't have to walk into the kitchen and explain to the chef which vegetables to chop, or know which suppliers the restaurant uses, the oil they cook with or how the oven is calibrated.

You just sit at a table, read the menu, order something from the server, then wait a reasonable amount of time for the server to return with your plate of food.

Here, the server is the bridge between you and a world you don't need to understand.

They take what you said and turn it into something the kitchen can act on, then bring back what the kitchen produced so you don't have to learn another job just to get fed.

This is exactly how APIs function.

In software, an API is the server at your table. It's a defined way for one piece of technology (you, sitting at the table) to ask another piece of technology (the kitchen) to do something useful, without having to know anything about how the kitchen actually works.

The Menu Is a Promise

Let's slow down at the menu, because this is where most of the structure lives that new developers try to breeze past it.

Think about what a menu actually is. It's a list of things the restaurant has decided you're allowed to ask and generally tell you the name of each dish, what's in it and roughly what you'll pay.

It also tells you what you can't ask for too because you won't find "build me a custom car" on a menu at an Italian place or "rewire my house" on the dessert list.

The menu sets the boundary of the conversation.

An API has a menu of its own and it's usually called the documentation, sometimes the API reference, or the contract.

The format is different but the roles are identical. It lists every request you're allowed to make, what you need to include with each one and what you'll get back in return.

If a developer is building an app that needs to talk to a weather service, the first thing they do is read the "menu". The weather service's documentation tells them the questions it can answer, exactly how to ask each one and what is returned back.

This is a contract between two pieces of software, written down ahead of time so neither side has to guess.

Without a menu, every interaction would be a guessing game. You'd walk in, ask for something, hope the kitchen could make it, then watch the server come back confused.

Software talking to software has the same problem at a much larger scale and the menu is what stops everything from falling apart.

Placing the Order Is the Request

You've read the menu and know what you want, now the next step is to place an order.

Notice what happens when you place an order, you don't simply say "food." You have to be more specific like, "I'll have the pepperoni pizza, no olives with a side salad."

This is much more detailed with some structure. There's a main item, modifications and there's something extra. The server writes it down or types it on a tablet and walks the order back to the kitchen.

In API language, what you just did is called a request which is a structured message that says "please do this specific thing for me and here are the details you need."

There's also a few other standard pieces included here.

There's the action you're asking for. What are you trying to do? Are you trying to read something, create something, change something or remove something?

In a restaurant, the verbs are roughly the same. Order, modify, cancel.

There's also the target. Which specific thing on the menu are you talking about? You want the pepperoni pizza not the carbonara. Then there's the details. The extra information the kitchen needs to get your order right like, no olives, extra cheese, on the side, well done.

Software does the same thing but even cleaner.

A request to a weather service might say "give me the current weather for the postal code 90210." A request to a music streaming service might say "add this song to the playlist with this ID."

It's the same shape, every time, an action, target and details.

The Response is the Plate Coming Back

So the order's been sent, you've waited some time, now the plate arrives at your table.

If everything went well, the plate has what you asked for. It might also come with a few things you didn't explicitly request, like cutlery, a napkin and a small piece of bread on the side. The restaurant has decided those are part of the package and you're glad they did.

If something went wrong, the plate doesn't come and the server will come back instead with a message, "we're out of fresh basil, would you like to swap that for arugula", or "the kitchen is backed up, it'll be another fifteen minutes", and in the worst case, "we couldn't make that and here's why."

What you've just received in any of those scenarios is a response which is the answer to your request. In a restaurant, the answer is a plate of food (or an explanation of why there isn't one). In software, it's a structured message that contains the result of what you asked for.

A response usually has two pieces worth knowing.

The status, which answer questions like, did the request succeed or fail? Was it partially fulfilled? Was it rejected because you asked for something the kitchen doesn't make?

In software, there are standard status codes that represent this scenarios.

The famous "404" means "I looked for what you asked for and couldn't find it."

The "200" means "all good, here's what you wanted."

A "500" means something went wrong on the kitchen's side and it's not your fault.

The content is the actual answer, like the plate of food or the current temperature in 78 degrees or the list of songs on the playlist, whatever the request was for.

Now the cycle is complete and that round trip (request out, response in) is the heartbeat of every API interaction in the world. Every app on your phone, website you've ever loaded and smart device in your house is doing some version of this, often dozens of times a second.

You Don't Need to Know How the Kitchen Works

This is the part that took me the longest to internalize when I was starting out and it just might be the most important.

When you order a pepperoni pizza, you don't know which brand of flour they used or whether the dough was made fresh that morning or the night before.

You don't know if the chef trained in Naples or learned from YouTube. You also don't know which oven they used, what temperature it runs at or how long the pizza sat under a heat lamp on the pass before the server picked it up.

None of that information is on the menu and you don't need any of it to enjoy your meal.

The restaurant has, on purpose, drawn a line between "things the customer needs to know" and "things the kitchen handles internally." On one side of the line is the menu, the order ticket and the plate and on the other side is everything else.

APIs operate the same way and it has a name. It's called the interface, which is the "I" in API.

The interface is the agreed surface between two pieces of software, specifically designed to expose only what the other side needs to interact with it. Everything behind that surface (the database, business logic, servers, code, the team, the company politics) is hidden.

This separation is the real reason APIs exist as it lets the kitchen change everything about how it operates (new chef, new oven, new supplier, new cooking technique) without you, the customer, having to relearn how to order.

As long as the menu still says "pepperoni pizza" and a recognizable pepperioni pizza still arrives at your table, you don't care what changed behind the wall.

In software terms, this is what lets a company like a payment processor swap out their entire backend over a weekend without any of their customers noticing. Whatever they did in the kitchen is none of your concern so as someone learning software, you get to skip a huge amount of complexity when you start using APIs.

The Internet Version of the Same Story

Up to this point, everything we've described could happen in a single building. The customer, the server and the kitchen are all under one roof but the most interesting APIs in software aren't in one building.

The customer is on a phone in London and the kitchen is in a data center in Virginia, so the order has to travel.

That travel happens over the internet and the way it travels is through HTTP, short for HyperText Transfer Protocol. This is the standard way computers send requests and responses to each other across the internet.

HTTPS is the same thing with a security layer wrapped around it, so nobody snooping on the network in between can read your order or tamper with the plate on the way back.

You've actually been using HTTP and HTTPS your whole life without thinking about it because every web address you've ever typed starts with one of them.

The "https://" at the start of a URL is the browser saying "I'm about to send a request using this protocol." The website on the other end is saying "I speak that protocol, send it over."

Picture our restaurant again, except now imagine the customer is at home and the kitchen is across town.

The customer calls the restaurant on the phone, places an order, hangs up and an hour later a delivery driver arrives with the food. The phone line and the delivery van are doing the job that HTTP does in software. They're the transport, the way the request gets from your side to the kitchen and the way the response gets back.

The shape of the conversation is identical to the in person version. There's still a menu, you still place an order and still get a response.

The only difference is the order is traveling over wires and radio waves instead of being walked across a dining room floor but everything we said earlier about requests and responses still applies.

A Real Example, in Plain Language

Let's walk through one round trip end to end, with as little jargon as possible to see all the pieces in motion.

You open a weather app on your phone to know if you need an umbrella today.

The phone, behind the scenes, looks up your location, then it puts together a request, which says, in software-speak, something close to "give me the current weather for these coordinates." That request is wrapped in HTTPS and sent over the internet to a weather company's API.

The weather company's servers (the kitchen) receive the request. They look at it, check that it's a valid order from the menu, do whatever work they need to do internally to figure out the answer (probably reading from a database that's being updated by satellites and ground stations every few seconds) and prepare a response.

The response comes back to your phone and contains a status (everything went fine, here's your data) and the content (it's 18 degrees, partly cloudy, 12 percent chance of rain).

Your phone reads that response, picks the parts it cares about and shows you a friendly little screen with a sun icon and a temperature.

Now you can decide to leave the umbrella at home.

That entire round trip took less than a second and happened completely silently. You didn't have to know which weather company answered, what protocol the request used, or how the kitchen kept its forecasts up to date. You just tapped a button and got an answer.

When API work well, you will not notice it. The whole point of the interface is to be quiet enough that you can think about your actual problem (do I need an umbrella?) instead of the plumbing underneath.

Why This Matters for Almost Every App You Use

When you tap "log in with Google" on a website you've never visited before, that website is making an API call to Google. The request says, roughly, "this person says they're a Google user, can you confirm that and tell me their name and email?" Google's API checks, sends back a yes or no with the relevant details and the website lets you in.

The website never sees your Google password and it doesn't need to. The API gave it the answer it actually needed.

When you order a ride from one of the big rideshare apps like Uber, or Lyft, your phone is having a multi-way conversation, calling a maps API to figure out the route.

It's calling a payment API to charge your card, calling a notifications API to send a text to the driver and calling a pricing API to calculate the fare.

None of those services are owned by the rideshare company. They're separate kitchens, each one with its own menu, all of them being asked to do their part by the app you tapped.

The reason modern software can be built quickly is that no team has to build everything from scratch. If you're starting a company tomorrow and you need maps, payments, email delivery, text messages and user authentication, you don't have to build any of those.

You read the menus of services that already do those things well, place the orders and get on with building the part of your idea that's actually new. This is an enormous shift from how software used to be built and APIs are the mechanism that makes it possible.

It's also why developers care so much about good API design. A confusing menu, a server that takes ten minutes to bring the plate, a kitchen that randomly refuses to make things it claimed it could, those are the kinds of problems that make customers walk out of the restaurant and never come back.

The same is true in software. An API that's hard to use will lose to one that's easy to use, even when the kitchen behind it is technically more capable.

The Different Flavors of APIs You'll Hear About

When you start reading about APIs in the wild, you'll bump into a few different terms that get thrown around as if they're competing technologies.

They're just different styles of menu, different ways of organizing the same conversation and knowing the names is useful but knowing the deep differences in detail is something you can pick up later.

REST APIs are the most common style on the public internet. The name stands for Representational State Transfer, which is one of those acronyms you can safely forget. The important part is that REST APIs use the standard verbs of the web (GET to read, POST to create, PUT or PATCH to update, DELETE to remove) and they organize their menus around things called resources. A REST API for a library might let you GET a book, POST a new book to the catalog, PATCH a book's details and DELETE a book that's no longer in circulation. The shape of the menu mirrors the shape of what you're working with.

GraphQL APIs take a different approach. Instead of giving you a long menu of pre-defined dishes, they give you a kind of build-your-own-bowl experience. You tell the kitchen exactly which fields you want back, and the kitchen sends back only those fields. This is useful when an app needs slightly different slices of data in different places and the team would rather not maintain dozens of slightly different menu items. GraphQL is more flexible and the tradeoff is that it can be more work to set up and to keep performant.

SOAP APIs are an older style you'll still see in banking, government and other industries that move slowly on purpose. They're more formal, more verbose and more strict about the shape of every request and response. If REST is a relaxed neighborhood bistro and GraphQL is a build-your-own poke bowl place, SOAP is the kind of restaurant where the menu is in three languages and the waiter wears a tie. It works, it's reliable, the experience is heavier.

Webhooks are worth mentioning even though they invert the usual pattern. With a normal API call, you walk into the restaurant and place an order. With a webhook, you've left your phone number with the restaurant and they call you when something happens. A common example is a payment service calling your app every time a customer's card gets charged. You didn't ask in that moment but you've set up the relationship ahead of time and the kitchen reaches out to you when there's news.

The thing to take away is that most of these styles are doing the same fundamental work we've been describing the whole post. Requests go out, responses come back, a menu defines the shape of the conversation.

The differences are in the texture of how each one feels to use and you'll develop preferences over time. For your first few projects, you're statistically most likely to be using a REST API and the mental model from this post will carry you a long way.

Where to Go From Here

You don't need to learn anything else right now. You need to use start using API's.

The single fastest way to make this concrete is to find a free public API and place a real order against it. There are several friendly ones designed for beginners, where you don't need an account, you don't need a credit card and you don't need to write a full app.

You can use a free tool called Postman or even your browser's address bar, type in a URL and watch a response come back.

After that, the natural next step is to read the documentation for an API behind a service you actually use. Pick something you're curious about like a music app, fitness tracker, calendar service, a public dataset from your government.

You should be able to notice that you can suddenly read it and be able to recognize much for the structure from this blog.

The world of APIs is huge and there are corners of it that take years to get good at but this version you've learned today is enough to start.

You should not be able to read most API articles, follow most tutorials and ask the right questions regarding API's especially when something isn't working.

And remember this, every app on your phone is just a customer at a table somewhere, placing an order and waiting for a plate.