API Requests
A waiter relaying your order
June 1, 2026 · 3 min read
The problem: systems that don't know each other
Your app needs weather data, or payment processing, or a map. It doesn't have direct access to the other company's database — nor should it. It needs a well-defined, safe way to ask a question and get a predictable answer back, without knowing anything about how that system works internally.
Like this
You don't walk into the kitchen and start pulling ingredients yourself. You tell the waiter what you want, in the format the restaurant expects — off the menu, not off the fridge.
Like this
You don't walk into the kitchen and start pulling ingredients yourself. You tell the waiter what you want, in the format the restaurant expects — off the menu, not off the fridge.
What an API request actually is
An API defines a contract: send a request shaped like this, to this address, and you'll get a response shaped like that. A request usually says what you want and any details it needs (an order); the response comes back with the result or an error (the plate, or “we're out of that”).
Like this
The menu is the API documentation. Ordering “table 12, the salmon, no onions” is the request. The plate that arrives is the response — or the waiter comes back and says they're out.
Like this
The menu is the API documentation. Ordering “table 12, the salmon, no onions” is the request. The plate that arrives is the response — or the waiter comes back and says they're out.
The catch: waiting, and things going wrong
Every request takes time, and every request can fail — the other system might be slow, down, or say no. Good systems plan for this: timeouts so you're not waiting forever, retries for the occasional hiccup, and sensible fallbacks when the answer just isn't coming.
Like this
Sometimes the kitchen is slammed and your order takes twenty minutes. A good waiter comes back to tell you that, instead of leaving you wondering if your order was ever heard at all.
Like this
Sometimes the kitchen is slammed and your order takes twenty minutes. A good waiter comes back to tell you that, instead of leaving you wondering if your order was ever heard at all.
Got a concept you want explained like this?
Ask me about itRelated explainers
New explainers, straight to your inbox
One email whenever a new concept goes up. No spam, unsubscribe anytime.