Learn how to design clean, predictable, and maintainable REST-style APIs around resources and HTTP semantics. Move beyond naive "REST = CRUD" simplifications to understand architectural constraints, safe vs. idempotent methods, hierarchical URL structures, parameter placement, and industry-standard conventions.
URIs represent nouns (resources), never verbs (actions). Let HTTP methods (GET, POST, PUT, PATCH, DELETE) define the operations executed upon those resources.
Deconstructing Roy Fielding's architectural style and distinguishing real REST from generic HTTP APIs.
In modern web development, the term REST (Representational State Transfer) is frequently used as a loose buzzword for any HTTP server that returns JSON. However, REST is not a protocol, a software library, or a standard JSON format. It is an architectural style introduced by computer scientist Roy Fielding in his 2000 doctoral dissertation on network-based software architectures.
GET and POST is not automatically RESTful. REST is an intentional architectural contract built upon resources, representations, statelessness, and a uniform interface.The central abstraction in REST. Any conceptual entity that can be named and addressed is a resource: a user, a product catalog, an order, or a real-time weather report. Every distinct resource is assigned a persistent, unique identifier (URI).
Clients never directly manipulate raw database tables or memory. Instead, clients exchange representations of the resource. A single user resource might be represented as application/json, application/xml, or text/csv. REST does not mandate JSON!
Provides a predictable, standardized interaction model across the entire distributed system:
• Resource identification via URIs (/courses/42)
• Manipulation via representations (HTTP verbs)
• Self-descriptive messages (Headers like Content-Type)
• Hypermedia controls (HATEOAS links guiding next possible actions)
Every client request to the server must contain all of the contextual information necessary to complete the operation. The server never stores client session state between requests. This allows servers to scale horizontally without sticky sessions.
Although Fielding designed REST to be protocol-independent, HTTP/1.1 and HTTP/2 are the natural embodiments of REST because HTTP already provides:
GET, POST, PUT, DELETE).200, 201, 404, 409).Accept and Content-Type to exchange representations.How to identify resources, structure intuitive URL hierarchies, and avoid RPC-style action endpoints.
The most frequent mistake in API design is treating URLs like remote procedure call (RPC) function names. In an RPC API, developers invent arbitrary verbs for every operation:
POST /createUser GET /getUserById?id=42 POST /updateUserAddress POST /deleteUser?id=42 POST /generateUserInvoice
In contrast, a Resource-Oriented REST API uses URLs exclusively to name nouns (the resources). The action being performed is expressed entirely by the standard HTTP method:
POST /users -- Create a new user in the collection GET /users/42 -- Retrieve representation of user #42 PATCH /users/42 -- Partially modify user #42 DELETE /users/42 -- Remove user #42 POST /users/42/invoices -- Create an invoice sub-resource for user #42
RESTful URLs follow a clear structural cadence:
/products): Refers to the set as a whole. Sending GET /products lists items; sending POST /products adds a new item to the collection./products/42): Refers to a specific entity identified by its key. Sending GET /products/42 inspects that single entity; sending DELETE /products/42 deletes it./orders/42/items): Represents items that conceptually live inside order #42./authors/12/books/45/chapters/2/paragraphs/8. Deep nesting is brittle, makes client code cumbersome, and creates tight coupling. If an entity has its own primary key, keep URLs flat: /paragraphs/8 or at most one level of parent scoping: /chapters/2/paragraphs.Connecting resource design with the precise semantics of Safe and Idempotent HTTP methods.
The IETF HTTP specification (RFC 9110) categorizes HTTP request methods by two crucial operational properties: Safety and Idempotency. These properties dictate how web clients, proxies, load balancers, and browsers interact with your API.
| Method | Safe? | Idempotent? | RFC 9110 Resource Semantic | Common Response Status |
|---|---|---|---|---|
| GET | YES | YES | Transfer a current representation of the target resource. Must NOT alter server state. | 200 OK |
| POST | NO | NO | Process the representation according to the resource's specific semantics; create subordinate resources. | 201 Created, 200 OK |
| PUT | NO | YES | Replace all current representations of the target resource with the request representation. | 200 OK, 204 No Content |
| PATCH | NO | NO (RFC 5789) | Apply a set of partial modifications or instructions to the target resource. | 200 OK, 204 No Content |
| DELETE | NO | YES | Remove the association between the target resource and its current functionality. | 204 No Content, 200 OK |
A request method is safe if its semantics are essentially read-only: the client does not request, and does not expect, any state change on the origin server.
Search engine crawlers, browser link pre-fetchers, and CDNs aggressively execute GET requests assuming they will never mutate data.
A method is idempotent if the intended effect on the server of multiple identical requests is the exact same as for a single request.
If a client sends DELETE /orders/42 and the network drops before receiving the response, the client can safely retry without side effects.
Developers often confuse PUT and PATCH:
{"name": "Alice"}, a strict PUT will erase the other 4 fields or fail validation!Establishing clear conventions for filtering, sorting, pagination, and status code signaling.
Every API request carries parameters. Clean REST design establishes clear rules for where each piece of data belongs:
Purpose: Identifies a specific resource or establishes hierarchy.
Rule of thumb: If removing the parameter changes WHICH entity is being addressed, it belongs in the path.GET /users/42/orders/108
Purpose: Filters, sorts, paginates, or shapes the representation.
Rule of thumb: If removing the parameter still targets the same base resource collection, it belongs in the query string.GET /products?category=books&sort=-price&page=2
-- Filtering by field value: GET /products?category=electronics&in_stock=true -- Sorting (prefix '-' or desc for descending): GET /products?sort=-price,created_at -- Pagination (page-based or limit/offset): GET /products?page=3&limit=20 GET /products?offset=40&limit=20 -- Field Selection / Projection: GET /users?fields=id,name,email
REST APIs communicate the result of operations through standard HTTP status codes:
200 OK — Standard response for successful GET, PUT, or PATCH.201 Created — Returned by POST when a new resource is created; should include a Location header with the new resource URI.204 No Content — Successful request where no body is returned (typical for DELETE).400 Bad Request — Malformed syntax or invalid client input.404 Not Found — Target resource URI does not exist.409 Conflict — Request conflicts with current resource state (e.g. duplicate email address).422 Unprocessable Content — Well-formed syntax but semantic validation failure.Practice designing endpoints for an Online Learning Platform. Match HTTP methods, URLs, parameters, and status codes to real requirements.
Resources available in domain: users, courses, lessons, enrollments.
Identify and fix real-world anti-patterns including action verbs in URLs, unsafe GET mutations, and excessive nesting.
GET /getAllUsers
The endpoint embeds an action verb ('getAll') into the URI instead of letting HTTP GET define the operation over a noun collection.
Design a consistent, production-ready REST API for an online bookstore across 5 core requirements.
Verify your ability to design complete API contracts. For each requirement below, choose the proper HTTP method, URI path, and expected success status code:
Key rules and heuristics for designing production-grade REST APIs.
/orders, /users), never actions (/getOrder, /deleteUser)./users/42). Query strings filter and paginate (?limit=10&sort=date).Model endpoints around resources (/courses, /users). Never embed action verbs like /createCourse or /deleteUser into paths.
GET must remain strictly read-only with zero mutations. Never trigger destructive side effects through query strings on GET.
Use PUT exclusively for complete replacement of a representation. Use PATCH when applying a partial set of field modifications.
Use URL paths to identify specific entities (/orders/101). Use query parameters for filtering, sorting, and pagination.
Avoid brittle 3+ level deep nesting. If an entity has a unique identifier, expose it directly on a top-level root endpoint.
Test your understanding of REST architectural constraints, RFC 9110 method semantics, and URL design conventions.