REST API explained: what's actually happening when your app "calls an API"

The one-sentence version

A REST API is just a set of URLs a server agrees to respond to in a predictable way, using the same HTTP that your browser already uses to load web pages. There's no separate secret protocol — "calling an API" is your app sending an HTTP request and reading the reply, exactly like a browser does.

The part that actually makes it "REST"

Strip away the jargon and the core idea is simple: every URL represents a thing — a resource, like a user, an order, or a photo — and the HTTP verb you use on that URL says what you want to do to it. GET reads it without changing anything, POST creates a new one, PUT or PATCH updates an existing one, DELETE removes it. GET /users/42 reads user 42. DELETE /users/42 deletes user 42. Same URL, different verb, completely different action. That pairing — noun in the URL, verb in the request — is the actual defining idea of REST, not anything more mysterious.

A concrete request, all the way through

Your app sends GET https://api.example.com/users/42 with a header like Authorization: Bearer <token> proving who's asking. The server checks that token, looks up user 42, and sends back a response with a status code — 200 for success, 404 if that user doesn't exist, 401 if your token wasn't valid — and a body, almost always JSON today, containing the actual data: {"id": 42, "name": "..."}. Your app never sees a database or a server's internals; it only ever sees that structured, agreed-upon reply.

What status codes actually communicate, and why it matters

The 2xx, 4xx, and 5xx groupings each mean something distinct. 2xx means it worked. 4xx means your app's own request was wrong somehow — a bad ID, missing authentication. 5xx means the server itself broke while trying to handle a perfectly valid request. This distinction genuinely matters for debugging: a 404 tells you to check what you're asking for, while a 500 tells you the problem is on their end, not yours — two very different next steps.

What people get wrong

"REST APIs always return JSON" — REST as a concept doesn't require JSON at all. It predates JSON becoming the default, and can technically return XML or plain text just as validly. JSON simply won the popularity contest because it's lightweight and every language can parse it easily, so it became the near-universal default in practice, not a requirement of REST itself.

One caveat worth knowing

Not everything called a "REST API" in the wild is actually purist REST by the strict academic definition. Most real-world APIs bend the rules slightly — skipping some of the stricter constraints from the original definition — and nobody in the industry treats that as a real problem. "RESTful," in casual, everyday use, just means "a JSON-over-HTTP API organized around resources and verbs," which is the practical definition worth knowing over the academic one.