How Does an API Work? – Request, Processing, Response
Follow one API call end to end: DNS and TLS, routing, authentication, validation, handling, serialisation, and what the status code actually reports.
An API call looks like a single function invocation from the caller's side. Underneath it is a sequence of stages, and knowing which stage failed is what turns an opaque error into a fixable one.
1. Resolve and Connect
The hostname is resolved to an address, a TCP connection is opened, and a TLS handshake establishes encryption. The handshake also carries the requested hostname, so a server hosting many domains knows which certificate to present.
Failures here — resolution errors, certificate mismatches, handshake refusals — happen before the API sees anything, which is why they produce network errors rather than status codes.
2. Route the Request
The request arrives at an edge or load balancer and is routed by host and path. This layer commonly applies rate limits, bot rules, and caching before the application is involved.
A response can therefore be produced entirely at the edge — a 429, a challenge page, or a cached body — without the application ever running.
3. Authenticate and Authorise
The application identifies the caller from a header credential, then checks whether that caller may perform this operation on this resource.
| Outcome | Status | Meaning |
|---|---|---|
| No or invalid credential | 401 | Not authenticated |
| Valid credential, insufficient rights | 403 | Authenticated but not permitted |
Confusing these two is a common client-side debugging error: the first is a credential problem, the second is a permissions problem.
4. Validate the Input
Parameters and body are checked against the expected schema — types, required fields, ranges, enumerations. Invalid input returns 400, ideally with a body naming which field failed and why.
Validation before side effects matters: a request rejected here has changed nothing.
5. Do the Work
The handler executes: query a database, call another service, run a computation. This is the only stage where the API's actual purpose happens, and usually the slowest.
Long operations may return 202 Accepted with a location to poll rather than holding the connection open.
6. Serialise the Response
The result is converted to the negotiated format — normally JSON, chosen from the Accept header — and returned with a status and headers describing type, caching, and rate-limit state.
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Remaining: 42
{"data": {"id": "A-4192", "name": "..."}}
7. Reading the Status Correctly
- 2xx — the request was accepted and processed.
- 3xx — go elsewhere; a redirect the client should follow.
- 4xx — the caller must change something: credential, permission, input, or rate.
- 5xx — the server failed; the same request may succeed later.
The class tells you who owns the fix, which is the fastest triage available.
8. Summary
An API call resolves, connects, routes, authenticates, authorises, validates, executes, and serialises. Errors are cheapest to diagnose when mapped to the stage that produced them.
Network errors precede the application; 401 and 403 separate identity from permission; 400 means the input never reached the handler; 5xx means it did and something broke.