REST API Cheatsheet
Master REST API fundamentals interactively: learn the 6 REST principles, break down URL anatomy, explore HTTP methods, and simulate filtering and pagination.
Continue with the guided workspace
Use the paired workspace to connect this guide's mental model with live component state, visible signals, and the outcome each step or scenario is meant to prove.
Representational State Transfer (REST) is the architectural style behind most web APIs. It treats server-side data as resources addressed by URLs and manipulated through a small set of uniform HTTP verbs, keeping the client and server decoupled, stateless, and cacheable so the system stays scalable and predictable.
Mental Model
At its heart, REST is about resources (like users, products, or posts) and state transfers (reading, creating, modifying, or deleting those resources over standard web channels). By separating the client from the server, standardizing on stateless communication, and structuring requests with uniform resource URLs and HTTP verbs, REST makes web systems scalable, predictable, and highly decoupled.
Components and Why They Exist
Client (User Browser)
The client browser is the decoupled frontend that initiates HTTP resource requests. It formats request URLs, headers, and JSON payloads before parsing the returned HTTP status codes and resource representations.
Proxy / Gateway
The proxy or API gateway is the intermediary layer that handles security, caching, and request routing. By intercepting incoming traffic and serving cached responses on repeated GET calls, this gateway prevents redundant traffic from reaching the backend server.
API Server
The API server is the stateless backend coordinator that executes resource business logic. It parses URL path variables and query strings, routes operations according to the HTTP method verb, validates payloads, and coordinates database calls.
Database
The database is the persistent source of truth for application resources. Query parameters for filtering and pagination translate directly into indexed database lookups here before the server formats and returns the matching resource collection.
Edge Cases and Misconceptions
PUT vs. PATCH for Updates
A frequent mistake is using PUT for partial modifications. If you send a PUT request with only one field (e.g. updating age), any fields omitted from the payload will be overwritten with default or null values because PUT replaces the entire resource. PATCH must be used for selective, partial updates.
Stateless Server vs. Local Client Caches
While the REST server must be stateless, clients and intermediaries (like CDNs) are allowed to cache responses. This means state is not stored on the server to identify the client session, but the data can still reside closer to the client to boost speed.
POST Idempotency
POST requests are not idempotent. If a network timeout occurs and a client retries a POST request, they risk creating duplicate resources (like placing the same order twice). In contrast, retrying PUT or DELETE requests is safe because the end state remains identical.
Common Questions
What are the 6 core principles of REST architecture?
The 6 principles are: 1) Client-Server separation (decoupling user interface from data storage), 2) Statelessness (no session state stored on the server), 3) Cacheability (explicitly marking responses as cacheable or not), 4) Layered System (transparency of intermediary servers like proxies or gateways), 5) Code-on-Demand (optional client-side script execution), and 6) Uniform Interface (predictable URI and method contract).
Why is statelessness important in REST APIs?
Statelessness means each client request must contain all the information necessary to understand and complete the request. The server does not store session state, which makes scaling horizontal clusters much easier since any server can handle any request.
What is the difference between PUT and PATCH?
PUT is used for replacing a resource entirely, requiring the client to send the full representation. PATCH is used for partial updates, where the client only sends the specific fields that need to change.
How does a Layered System improve API architecture?
In a layered system, the client cannot tell whether it is connected directly to the end server or through intermediaries like load balancers, proxies, API gateways, or CDNs. This allows developers to introduce security policies, caching layers, and load balancing transparently.
What is the recommended URL design for REST endpoints?
Endpoints should use plural nouns rather than verbs (e.g., `/users` instead of `/getUsers`). They should follow a clear path hierarchy (e.g., `/users/1/posts`) and use query parameters for filtering, sorting, and pagination (e.g., `/users?limit=10`).
What makes an HTTP method 'safe' vs 'idempotent'?
A method is 'safe' if it does not modify resource state on the server (e.g., GET, HEAD). A method is 'idempotent' if executing it multiple times produces the same server state as executing it once (e.g., GET, PUT, DELETE). POST is neither safe nor idempotent.