Every time Zomato shows you a restaurant's menu, your bank balance appears in a fintech app, or Google Maps loads inside Uber — an API is doing the work. Here's exactly how.
What's actually happening here?
An API (Application Programming Interface) is a formally defined contract between two programs. One program says: "if you send me a request in this exact format, I will send you back a response in this exact format." That's it. The caller doesn't need to know how the other side works internally — just what to send and what to expect back.
The most important word is contract. Not a suggestion. Not a convention. A contract both sides agree to and are held to.
The problem this solves
Without APIs, every company would need to build everything from scratch. Want to accept payments? Build a bank. Want to show a map? Collect satellite imagery of the entire earth. Want to send an SMS? Build a telecom network.
APIs let specialisation exist at internet scale. Stripe handles payments, Google handles maps, Twilio handles SMS — and every other company just calls their API. The entire modern software industry is built on this division of labour.
How it really works (step by step)
The request-response cycle over HTTP:
Client decides what it needs — "I want the menu for restaurant ID 4821." It packages this as an HTTP request with a method (GET), a URL (
/restaurants/4821/menu), and optional headers (auth token, content type).Request travels over the internet — same packet-routing journey as any HTTP call. Usually hits a load balancer first, which forwards to one of many API server instances.
API server receives and validates — checks the auth token is valid, the restaurant ID exists, the caller has permission to see this data. Invalid requests are rejected here — never touch the database.
Business logic runs — the server fetches data from its database, applies any rules ("is this restaurant currently open?"), and builds the response object.
Response serialised to JSON — the data structure is converted to a text format (almost always JSON today) that any language on any platform can parse.
HTTP response returned — includes a status code (200 OK, 404 Not Found, 429 Too Many Requests), headers (content type, rate limit remaining), and the body (the JSON data).
Client parses and uses the response — the calling app reads the JSON, extracts what it needs, and renders it for the user.
The part most tutorials skip
Status codes are part of the contract — and most APIs use them wrong. Returning 200 OK with {"success": false, "error": "not found"} in the body is a broken API. The HTTP status code is the machine-readable result. Clients, load balancers, monitoring systems, and CDNs all make decisions based on status codes — not the JSON body. A 404 tells the CDN not to cache the response. A 429 tells a client to back off. A 503 tells a load balancer to try a different backend. Use them correctly or every layer in the stack misbehaves.
Real company doing this right now
Stripe's API is the gold standard for API design — used by millions of developers worldwide. Three decisions make it exceptional. First, every object has a globally unique prefixed ID (cus_, pi_, ch_) so you instantly know what type of object you're looking at in any log. Second, every mutating operation accepts an Idempotency-Key header — if your payment request times out and you retry, Stripe detects the duplicate and returns the original result instead of charging twice. Third, their API has been backwards-compatible since 2011 — they never remove a field, they only add. Existing integrations from 2011 still work today without changes.
What breaks at scale?
Chatty APIs kill performance. A poorly designed API might require 12 separate calls to load one screen — fetch user, fetch their orders, fetch each order's items, fetch each item's image URL. At 1 million users, that's 12 million database queries for one screen render. The fix is designing APIs around what the client needs (one call per screen) rather than what the database has (one call per table). This is exactly the problem GraphQL was invented to solve — but it's also solvable by designing REST endpoints around use cases rather than resources.
The "aha" moment
An API is not code — it's a promise. The implementation behind it can be rewritten in a different language, moved to a different server, or completely restructured — as long as the promise (the contract) stays the same, no caller ever needs to know or care.
Your practical takeaway
Design API endpoints around what the client needs, not what your database looks like — a
/dashboardendpoint that returns everything a dashboard needs in one call is better than 8 separate resource endpoints the client has to assemble.Use HTTP status codes correctly from day one —
200means success,400means the caller did something wrong,500means your server did something wrong. Getting this right makes debugging, monitoring, and client error handling dramatically simpler.Add idempotency to any endpoint that creates or modifies data — accept an
Idempotency-Keyheader, store it with the result, return the cached result on duplicate requests. This makes your API safe to retry and eliminates a whole class of double-action bugs.
Lesson 04 · Stage 1 — Network Foundations · System Design Made Easy for all