How APIs Actually Work: A Plain-English Guide

Last week I stood at a kiosk at the airport and tapped a screen to buy a coffee. I never touched the espresso machine. I never walked into the back to find beans. I pressed a picture, my phone buzzed, and a minute later a cup appeared with my name spelled almost right. Between my tap and that cup, a dozen invisible conversations happened: the kiosk asked the payment system "is this card real?", the payment system asked my bank "does she have the money?", the bank answered "yes," and the kiosk told the kitchen "make one flat white."

None of those systems share a brain. They don't even speak the same internal language. But they agreed, ahead of time, on exactly how to ask each other questions and exactly how to answer. That agreement has a name. It's an API.

The waiter, and then past the waiter

The classic way to explain an API is the restaurant waiter, so let me start there and then keep walking.

You sit down. You don't go into the kitchen, grab a pan, and start cooking. You also don't need to know whether the chef uses gas or induction. You read a menu, you tell the waiter what you want, and the waiter brings it back. The waiter is the messenger with a fixed set of rules: you can order things on the menu, in a certain way, and you'll get a predictable result.

API stands for Application Programming Interface, but forget the words. The thing that matters is the word interface. An API is a menu plus a waiter. It's a published list of things you're allowed to ask a piece of software, and a reliable way to ask for them. You never see the kitchen. You don't need to.

Here's where I want to go past the analogy, because the waiter version stops being useful fast. In real software, the "menu" is a list of web addresses, the "order" is a structured message, and the "kitchen" might be a weather service in Norway, a bank in Tanzania, or an AI model on a server you'll never visit. The rules just have to be written down clearly enough that two programs that have never met can still cooperate.

Request and response: the whole game

Almost every API works on one simple loop: you send a request, you get back a response. That's it. Everything else is detail layered on top of those two words.

A request is you saying "here is what I want." A response is the other system saying "here is what I have" (or "here's why I can't"). When your weather app shows you tomorrow's rain, it sent a request to a weather company's servers and got a response full of numbers. When you tap "pay," your app sent a request and waited for a response that said approved or declined.

The internet runs on this loop billions of times a second. Your phone is constantly sending tiny requests and getting tiny responses, mostly without you noticing.

Endpoints: the specific doors

If the API is the building, endpoints are the labelled doors. Each endpoint is a web address that does one specific job.

Imagine a weather service. It might offer:

• api.weather.com/today — give me today's weather
• api.weather.com/forecast — give me the next seven days
• api.weather.com/alerts — give me any storm warnings

Same service, different doors. You knock on the one that matches what you need. A good API documents every door so you know what's behind it before you knock.

Methods: what you're trying to do at the door

Knocking isn't enough. The system also needs to know your intent. Are you reading something, adding something, changing something, or deleting something? That's what HTTP methods (sometimes called verbs) describe. There are four you'll meet constantly:

• GET — read. "Show me my profile." GET never changes anything; it just fetches.
• POST — create. "Add this new comment." POST makes something new exist.
• PUT — update. "Change my email to this." PUT replaces or updates existing data.
• DELETE — remove. "Delete this photo." Exactly what it says.

I find it helps to think of a notebook. GET is reading a page. POST is writing a new page. PUT is erasing a page and rewriting it. DELETE is tearing the page out. Same notebook, four different actions, and the API needs you to be clear about which one you mean.

JSON: the shared language

Two programs written by strangers, on different continents, in different programming languages, still need to understand each other's words. The most common shared language for that is JSON (JavaScript Object Notation).

Don't let the name scare you. JSON is just a tidy way of writing down facts as labelled pairs. If I described myself in JSON, it would look like this:

{
  "name": "Happyness",
  "city": "Dar es Salaam",
  "writes_articles": true
}

That's it. A label on the left, a value on the right, wrapped in curly braces. A human can read it, and so can almost any programming language. When an API sends you a response, it's usually JSON. When you send data in a POST request, it's usually JSON too. It's the agreed handwriting everyone can read.

A real request and response, start to finish

Let me show you the whole loop with the weather example. Here's a request asking for today's weather in Dar es Salaam:

GET /today?city=Dar-es-Salaam HTTP/1.1
Host: api.weather.com
Authorization: Bearer your-api-key-here

The first line says the method (GET), the endpoint (/today), and a little extra detail (city=Dar-es-Salaam). The rest is the address and a credential I'll explain in a moment.

And here's the response the server might send back:

200 OK

{
  "city": "Dar es Salaam",
  "temperature_c": 31,
  "condition": "Partly cloudy",
  "rain_chance_percent": 20
}

The 200 OK at the top is a status code (more on that next), and the JSON underneath is the actual answer. Your weather app reads temperature_c, sees 31, and quietly puts "31°" on your screen. That's the entire trick. Everything you've ever loaded in an app is some version of this.

Status codes: the system's mood in a number

Every response comes with a three-digit status code that tells you, instantly, how things went. You've already seen 404 in the wild. There are dozens, but you mostly need three:

• 200 — OK. It worked. Here's what you asked for.
• 404 — Not Found. That door doesn't exist, or the thing you wanted isn't there. (Yes, this is the famous "page not found.")
• 500 — Server Error. You did nothing wrong; the kitchen caught fire. Something broke on their side.

The rough rule: codes in the 200s mean success, 400s mean you made a mistake (wrong door, missing info, no permission), and 500s mean they made a mistake. When something in an app fails, a developer's first instinct is to look at the status code, because it points the finger before you read a single word.

API keys and authentication: showing your ID at the door

Most useful APIs don't let just anyone walk in. They need to know who you are, partly so they can keep things secure and partly so they can keep track of who's asking. That's where API keys come in.

An API key is a long secret string of characters, a bit like a password that belongs to your app rather than to you personally. You include it with every request (you saw it above as Authorization: Bearer your-api-key-here). The server checks it and thinks, "ah, this is a known, allowed app — go ahead." Without it, you'd get a polite refusal, usually a 401 Unauthorized.

This whole "who are you and are you allowed?" question is called authentication (proving who you are) and authorization (what you're allowed to do once you're in). Keys are the simplest version. Bigger systems use fancier methods, but the idea never changes: prove yourself before you're served.

Rate limits: the bouncer counting heads

If you've ever been told "you're doing that too often, try again later," you've met a rate limit.

Servers have finite resources. If one app fired ten million requests a second, it could knock the service over for everyone. So APIs cap how many requests you can make in a window of time — say, 1,000 per hour. Go over, and you'll get a 429 Too Many Requests, which politely means "slow down." It's not punishment; it's the bouncer keeping the room from overcrowding so everyone gets served.

Why any of this matters

Here's the part I wish someone had told me early. APIs aren't a niche developer topic. They are the connective tissue of everything you touch on a screen.

Your maps app doesn't own the traffic data — it asks a traffic API. Your banking app doesn't process payments alone — it calls a payments API like a card network. Your favourite app's "Sign in with Google" button is an API conversation. And the AI tools everyone's talking about? When an app "uses AI," it's almost always sending your text to a model over an API and getting a response back. Same request-response loop, just with a very clever kitchen.

Once you see it, you can't unsee it. Modern software is mostly a polite, fast, endless conversation between programs that agreed in advance on how to talk. That agreement is the API. Understanding it turns the internet from magic into machinery — and machinery, unlike magic, you can actually learn.

If you're building toward a career in tech or AI, this is foundational. You don't need to memorise every status code. You need the shape of the thing: ask through a door, with the right method, prove who you are, get JSON back, read the status code. That shape repeats forever.

Frequently asked questions

What does API stand for, and do I need to remember it?

It stands for Application Programming Interface. Honestly, the full name isn't important. What matters is the idea: it's a defined, published way for one piece of software to ask another for something and get a reliable answer back.

Is an API the same thing as a website?

Not quite. A website sends back pages designed for humans to look at. An API sends back structured data (usually JSON) designed for other programs to read. The same company often runs both, sharing the same kitchen behind the scenes.

Do I need to know how to code to understand APIs?

No. Understanding what an API is and how the request-response loop works requires zero coding. Actually calling one in a real project does involve some code, but the concept is plain English, as this guide hopefully showed.

Why do some APIs cost money?

Running servers, storing data, and serving millions of requests costs real money. Many APIs are free up to a limit and then charge based on how many requests you make. That's also why rate limits and API keys exist: to track and meter usage fairly.

What's the difference between authentication and authorization?

Authentication is proving who you are, like showing ID at the door. Authorization is what you're allowed to do once you're inside, like which rooms you can enter. An API key handles the first; permission rules handle the second.

Further reading on this site

• How to Start Learning AI in Tanzania — where understanding APIs becomes a real skill.
• Browse Technology — more plain-English explainers like this one.

If this made APIs click for you, subscribe to the newsletter and I'll send the next plain-English breakdown straight to your inbox.

Sources

1. 1.An overview of HTTP— MDN Web Docs
2. 2.HTTP response status codes— MDN Web Docs
3. 3.JSON: Working with JSON— MDN Web Docs