How APIs Actually Work

An API is a contract, not a tool. Start here and the rest follows.

An API is a contract between two roles, client and server — not a specific tool, protocol, or format. Once you see it as a promise about addresses and shapes rather than code, questions like 'what should I expose' and 'how do I secure it' start answering themselves.

Trace one request end to end and the front/back-end fog lifts.

Client and server are roles, not fixed identities — your backend becomes a client the moment it calls another service. Tracing one request end to end, naming who initiates and who responds at each hop, is what actually clears up the front-end/back-end confusion.

What "expose an endpoint" really means: DNS, ports, and binding.

'Expose an endpoint' hides four real stages: DNS resolving a name to an address, a port acting as the door, a bind decision (localhost vs. the world), and a path routing to the code that answers. Each stage fails differently, so knowing which one broke turns a vague symptom into a specific fix.

Why every request re-introduces itself — and where state lives.

HTTP servers are deliberately stateless, which is what lets any server handle any request and the web scale horizontally. The cost is that identity has to be re-proven on every single call — the entire reason sessions, cookies, and tokens exist.

Methods, status codes, headers, body — the contract in detail.

Every HTTP message reduces to four parts with fixed jobs: a method (the verb), a path (the noun), headers (metadata), and a body (payload) — answered by a status code, more headers, and a payload. Learn the four slots and "design an endpoint" stops being a mystery.

Watch the anatomy you just learned on real, live traffic.

curl -v and the browser Network tab expose the exact anatomy from the last step on real, live traffic — handshakes, headers, redirects, and preflights you have been trusting on faith. Reading the whole conversation, not just the response body, turns "the API is being weird" into a specific fact.

Who you are vs what you may do — and where each check happens.

Authentication answers "who are you"; authorization answers "what may you do" — two separate checks that belong in different places, since identity can be offloaded to a gateway but permission checks belong in the service that owns the resource. Conflating them is the root cause behind most broken-access-control vulnerabilities.

TLS termination: where encryption actually stops in production.

"Put it behind HTTPS" is the start of securing an API in transit, not the end — the real question is where the lock comes off and what protects every hop after it. The current standard answer is mTLS on every leg, not "trust the internal network."

The front door that owns the public address and guards your services.

In production your backends are not directly exposed — a single reverse proxy or API gateway owns the public address, terminates TLS, routes by path, and authenticates callers before traffic ever reaches your code. "Is this endpoint exposed?" becomes a question about the gateway config, not your service.

The browser rule that makes APIs "work in curl but not the app."

CORS is not the browser being difficult — it is the browser protecting your users by refusing, by default, to let an arbitrary site spend their credentials against your API without permission. The fix for a CORS error is always a specific server-side header, never a client-side workaround.