REST API Design Principles & Resource Modeling

Representational State Transfer (REST) was defined in 2000 by Roy Fielding in his doctoral dissertation. REST is not a rigid protocol or specification; it is an architectural style governed by six core constraints:

1. Client-Server Architecture: Separates user interface concerns (clients) from data storage and business logic (servers), enabling independent evolution and scaling.
2. Statelessness: Every request from client to server must contain all the contextual information needed to understand and process the request. The server must never store client session context in server memory between requests. Session state belongs entirely on the client (or in an external shared session store like Redis).
3. Cacheability: Responses must explicitly declare themselves as cacheable or non-cacheable via HTTP headers (Cache-Control, ETag, Expires) to eliminate redundant server round-trips.
4. Uniform Interface: The cornerstone of REST. Resources are identified in requests via standardized URIs; resource manipulation occurs via self-descriptive representations (JSON, XML); messages are self-describing with standard MIME types and status codes.
5. Layered System: A client cannot tell whether it is connected directly to the end server or to an intermediary proxy, CDN, load balancer, or API gateway.
6. Code-on-Demand (Optional): Servers can temporarily extend client functionality by transferring executable code (e.g., JavaScript).

Resource-oriented design models systems around nouns (entities) rather than verbs (remote procedure calls).

The Plural Noun Convention:

Endpoints should always represent collections of plural nouns:

• GET /v1/customers (Retrieve list of customers)
• POST /v1/customers (Create new customer)
• GET /v1/customers/cus_89f0 (Retrieve specific customer)
• PUT /v1/customers/cus_89f0 (Full replacement of customer)
• PATCH /v1/customers/cus_89f0 (Partial update of customer)
• DELETE /v1/customers/cus_89f0 (Delete customer)

Sub-Resource Nesting (Max 2 Levels):

Nested endpoints express natural ownership and parent-child relationships:

• GET /v1/customers/cus_89f0/orders (List orders belonging to customer cus_89f0)
• POST /v1/customers/cus_89f0/orders (Create an order for customer cus_89f0)

[!WARNING] Anti-Pattern (Deep Nesting): Avoid nesting beyond two levels (e.g., /orgs/1/depts/2/teams/3/projects/4/tasks/5). Deeply nested URLs become brittle, difficult to refactor, and tightly coupled. Flatten sub-resources to top-level endpoints once the child entity has a globally unique ID (e.g., GET /v1/tasks/5).

Filtering, Sorting, and Field Selection:

Use query parameters to filter, sort, and paginate resource collections without creating ad-hoc URL paths:

http
Copy
GET /v1/orders?status=fulfilled&created_at_gte=2026-01-01&sort=-total_amount&limit=25&fields=id,status,total_amount

HTTP methods provide standardized semantics regarding safety and idempotency:

• Safe Method: A method that does not modify server state (GET, HEAD, OPTIONS). Clients can call it repeatedly without side effects.
• Idempotent Method: Making N identical requests produces the exact same server state as making 1 request (GET, PUT, DELETE, HEAD, OPTIONS).
• Non-Idempotent Method: Making N identical requests creates N separate side effects (POST, PATCH depending on implementation).

*Note: While PATCH is technically non-idempotent by RFC 5789 specification (e.g., incrementing a counter), in standard REST CRUD APIs, applying a static JSON patch ({"email": "new@example.com"}) is practically idempotent.

Returning the exact HTTP status code communicates outcome semantics without forcing client parsers to inspect arbitrary JSON strings.

Essential Status Codes:

• 200 OK: Standard successful response for GET, PUT, PATCH.
• 201 Created: Successful resource creation (POST). Must include the Location: /v1/users/usr_981 header.
• 202 Accepted: Request received for asynchronous background processing; processing is not yet complete.
• 204 No Content: Successful request with zero response body (DELETE, empty PUT).
• 304 Not Modified: Conditional GET matches client cache (If-None-Match / ETag).
• 400 Bad Request: Malformed JSON syntax or schema failure.
• 401 Unauthorized: Authentication missing or invalid (no valid token/credentials).
• 403 Forbidden: Authenticated, but user lacks permission to access this resource.
• 404 Not Found: Resource URI does not exist.
• 409 Conflict: State conflict (e.g., unique constraint violation, concurrent edit collision).
• 422 Unprocessable Entity: Valid JSON syntax, but violates business validation rules.
• 429 Too Many Requests: Rate limit exceeded (should include Retry-After header).
• 500 Internal Server Error: Unhandled backend exception.
• 502 Bad Gateway / 504 Gateway Timeout: Downstream microservice error or timeout.

Standardized Error Payloads (RFC 9457 Problem Details):

json
Copy
{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Account Balance",
  "status": 422,
  "detail": "Account acct_981 has balance `12.50, but transfer requires`50.00.",
  "instance": "/v1/transfers/txn_4019",
  "invalid_params": [
    {
      "name": "amount",
      "reason": "Amount exceeds available balance"
    }
  ]
}

1. Verb-Driven URIs (RPC Tunneling):
   • ❌ POST /api/deleteUser?id=42
   • ❌ POST /api/createUser
   • ✅ DELETE /v1/users/42, POST /v1/users
2. HTTP 200 OK with Error in Body:
   • ❌ Returning 200 OK with {"status": "error", "message": "User not found"}. This breaks client error interceptors, load balancer health checks, and CDN caching layers.
   • ✅ Return 404 Not Found with RFC 9457 JSON body.
3. Leaking Database Schema Details:
   • ❌ Exposing internal auto-increment primary keys (id: 1042) or database column names directly (tbl_usr_pwd_hash).
   • ✅ Expose opaque prefixed UUIDs/ULIDs (id: "usr_01H12B...") and clean domain field names.