What is an API?
Follow one weather request from a phone to a database and back, and watch the restaurant analogy turn into real endpoints, keys, status codes and JSON.
Weather app
Every app on your phone is quietly talking to programs it did not write. An API is the agreed way one piece of software orders something from another. Picture a restaurant: you never walk into the kitchen, you just order.
API documentation
The menu comes first. API documentation lists every dish the kitchen will make, the exact words to use, and what comes back. Without it you are guessing, which is why good documentation is the most loved feature any API has.
The endpoint
An endpoint is the address of one dish. It pairs a verb with a path: get the forecast, create an order, delete a photo. The waiter reads that one line and knows exactly which station to walk it to.
API key check
First the waiter checks you are a real customer. Your app sends a secret key or a token, usually a long random string, tucked into a header. No key, no food: the server answers four zero one, unauthorized, and stops there.
Rate limiter
Restaurants seat a limited number of guests, and APIs limit how often you may ask. A typical free tier allows sixty calls a minute. Go over and you get four two nine, too many requests, with a note saying when to try again.
Input validation
Before anything real happens the server checks the order makes sense. A missing city name or a date in the year three thousand is rejected right here with four hundred, bad request. Never trust the caller is the oldest rule in server code.
Business logic
This is the kitchen, and nobody outside ever sees it. Business logic picks the forecast model, converts units, hides other customers' data and applies whatever rules the company sells. You are handed the dish, never the recipe.
Recent forecasts
Popular orders are kept warm. If somebody asked for London in the last ten minutes the answer is already sitting in memory and comes back in about two milliseconds instead of two hundred. A few big cities draw most of the traffic, so a good cache spares the kitchen the majority of calls.
Forecast database
On a miss the kitchen walks to the pantry. The database holds the real records and the API is the only door to it. That is the whole point: your app never gets a database password, only permission to ask a narrow set of questions.
Weather station feed
The pantry itself is restocked from outside. Weather stations, satellites and ocean buoys push readings in on a schedule, so the service you call is often a polished front for somebody else's data. APIs are built on APIs, most of the way down.
The response
Now the dish is plated. Back comes a status code, two hundred meaning fine, and a small block of JSON: a temperature, a condition, a timestamp. It is plain text, so any language on any device can read the same answer.
Error codes
Sometimes the kitchen is out of salmon. Codes in the four hundreds mean the caller made the mistake, codes in the five hundreds mean the server did. A good API says which one in plain words, because you can only fix your own half.
Logs and metrics
Every order is written in the books. Logs and metrics record who called what, how long it took and what failed. Teams watch the slowest one call in a hundred especially closely, because that long tail is what real users notice.
Forecast on your screen
Milliseconds later the forecast is on your screen and you never knew a stranger's computer was involved. That is a good API: a clear menu, a strict door, and a promise that the same order gets the same answer tomorrow.
Watch it explain itself
Every step above is narrated aloud. Play it, or open it in the editor and make it yours — no account needed.