How REST APIs Work — one request round trip
How REST APIs work, shown on an interactive canvas: building an HTTP request, routing and validation on the server, and the response that completes the round trip.
A REST API is a conversation in HTTP: the client sends a request that names a resource and an action, the server processes it, and the response carries a status code and the result.
How REST APIs Work — one request round trip
The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.
How to read this visual
- Read the three columns left to right: Request, Server processing, Response.
- The client row and server row alternate, so each arrow is either the client sending something or the server deciding something.
- The "Is the request valid?" decision feeds either the happy path or the Reject endpoint — the two outcomes every API call can have.
The request
"Client builds an HTTP request (method, URL, headers, body)" is the start of every REST interaction. The method is the verb — GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes — and the URL names the resource, so "/users/42" is the request to read one user. "Client sends the request over HTTPS" is the transport: REST rides on HTTP, and HTTPS keeps the conversation private over the same internet infrastructure the other visuals map.
The server's work
"Server routes the URL to the matching handler" maps the request to code, and "Is the request valid?" is the gate: authentication (who you are), authorization (are you allowed) and payload validation all happen here, with failures sent to the Reject endpoint "Server returns 400 / 401 / 403". "Handler runs the business logic" and "Server reads or writes the resource in the database" are the actual work — the part the client never sees.
The response
"Server builds the response with a status code and JSON body" is the contract in machine form: 200 for success, 201 for created, 404 for missing, 500 for a server fault. "Client receives the response and parses it" and "Client renders the result to the user" complete the loop — the round trip ends where it began, in the client, which is exactly why the visual returns to the client row.
Key relationships and takeaways
- REST is a contract in HTTP: methods are verbs, URLs are resources, and status codes are the machine-readable outcome.
- The client is stateless — every request carries everything the server needs, so no shared session is required.
- Validation is the security boundary; an invalid request is rejected before any business logic runs.
- The response is defined by its status code first and its body second.
- REST traffic rides the same DNS, HTTPS and internet infrastructure the other technology visuals map.
When to use this visual
- Teaching the HTTP method/URL/status model to engineers before they design their first endpoint.
- Reviewing an API's contract — are errors status codes or 200-with-a-flag? — against the REST convention.
- Grounding a conversation about idempotency and caching in how requests are actually built and validated.
How it works
Map your own endpoints onto the request box
Add notes listing your real methods and routes — GET /orders, POST /payments — so the diagram documents your API's surface.
Name your status codes
On the response step, annotate the codes your API actually returns for each outcome, and add the ones your contract uses beyond 200 and 400.
Add authentication
Insert the token step between the client and the validation gate — a JWT or OAuth token in the Authorization header — to show where identity enters the request.
Draw the retry and failure branches
Add explicit endpoints for network failure, rate limiting and server errors, each with the client behaviour (retry, backoff, error state) it triggers.
Frequently asked questions
What is a REST API?
A REST API is a set of HTTP endpoints that expose a system's resources. Clients act on resources with HTTP methods — GET to read, POST to create, PUT or PATCH to update, DELETE to remove — and the server responds with a status code and a representation, typically JSON. REST is a style rather than a standard, and its value is that any client that speaks HTTP can use it.
What is the difference between GET, POST, PUT and DELETE?
They are the verbs of the REST contract. GET reads a resource and should have no side effects. POST creates a new resource and returns its identity. PUT replaces a resource wholesale and is idempotent — repeating it changes nothing more. PATCH applies a partial update. DELETE removes a resource. Together the verbs plus the URL name the complete action, which is why the request box in the visual calls out the method first.
Why are status codes important in REST?
Because they are the machine-readable outcome of the request. A client can branch on the status code without parsing the body: 2xx success, 4xx the client's mistake, 5xx the server's. APIs that return 200 with an error flag in the body break this contract and force every client to special-case the response.
What makes an API 'RESTful'?
The practical checklist: resources named by URL, actions expressed as HTTP methods, stateless requests (each one carries everything the server needs), responses that use status codes properly, and often hypermedia or versioned URLs. The canvas models the round trip — request, validation, processing, response — which is the shape every RESTful exchange shares.
Edit this visual in QueryChart (FlowJam)
Open this exact REST canvas as your own chart, rename the client and server to your services, and annotate your endpoints.