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.
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.
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 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.
SOCIAL SHARE CARD GENERATOR