REST API Design — Resource Modeling & HTTP Semantics

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.

Core Architectural Concepts

Why REST Commonly Uses HTTP

Although Fielding designed REST to be protocol-independent, HTTP/1.1 and HTTP/2 are the natural embodiments of REST because HTTP already provides:

• Universal Resource Identifiers (URIs): Direct naming of resource locations.
• Standardized Request Verbs: Well-defined operational semantics (GET, POST, PUT, DELETE).
• Standardized Status Codes: Granular outcome signaling (200, 201, 404, 409).
• Content Negotiation Headers: Accept and Content-Type to exchange representations.

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

Collections vs. Individual Resources

RESTful URLs follow a clear structural cadence:

• Collection Resource (/products): Refers to the set as a whole. Sending GET /products lists items; sending POST /products adds a new item to the collection.
• Individual Item Resource (/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.
• Sub-Resource Collection (/orders/42/items): Represents items that conceptually live inside order #42.

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.

PUT vs. PATCH: The Critical Distinction

Developers often confuse PUT and PATCH:

• PUT (Replacement): You send the complete new representation. If a user has 5 fields and you send only {"name": "Alice"}, a strict PUT will erase the other 4 fields or fail validation!
• PATCH (Partial Modification): You send only the delta or specific fields to update. The server applies changes to the existing representation without touching other fields.

Every API request carries parameters. Clean REST design establishes clear rules for where each piece of data belongs:

-- 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

Appropriate HTTP Status Codes

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.

Verify your ability to design complete API contracts. For each requirement below, choose the proper HTTP method, URI path, and expected success status code: