Domain-to-Resource Mapping, Query Modifiers, HTTP Methods Safety/Idempotency, Status Codes, & Best Practices
1 Resource Modeling: From Business Domain to REST Endpoints
In RESTful (Representational State Transfer) architecture, real-world business entities are abstracted into pluralized, noun-based Resources identified by clean, intuitive, and predictable URIs.
🏢 1. Business Domain Entities (Data Layer)
Mapped to Pluralized REST Resource Collections
⬇️🌐 2. REST API Resource Collections (Interface Layer)
URIs represent things (resources), not actions. Use /orders instead of /createOrder or /getOrders. The HTTP method specifies the action.
Collections use plural nouns (/products). A specific entity is addressed via its unique identifier in the path (/products/{id}).
2 Hierarchical URL Patterns & Identifier Routing
Endpoints should follow a strict hierarchical structure with API versioning prefixes, plural noun resource paths, and unique resource identifiers:
/api/v1/products/api/v1/products/{id}/products/4d3e…)/api/v1/orders/api/v1/ordersWhen an entity is naturally owned by or subordinate to another parent entity, express the relation hierarchically in the path:
/api/v1/products/{productId}/reviews📌 Design Rule of Thumb: Limit nesting to a maximum of 2 levels deep (e.g., /products/{id}/reviews). Deeply nested paths like /users/1/orders/2/items/3/taxes indicate poor modeling; flatten them to top-level collections with query filters (/order-items?order_id=2).
3 Query Parameters: Filtering, Sorting & Pagination
Rather than creating dedicated endpoint paths for every query permutation, use standardized Query Parameters (?key=value) to modify, constrain, and structure collection responses.
WHERE category = ‘books’ AND in_stock = true to SQL query.[
{
“id”: 101,
“title”: “Designing APIs with Swagger”,
“category”: “books”,
“inStock”: true,
“price”: 29.99
}
]ORDER BY price ASC (use -price or price:desc for descending).[
{
“id”: 201,
“title”: “Wireframe UI Kit”,
“price”: 9.99
},
{
“id”: 202,
“title”: “Figma Pro Component Library”,
“price”: 19.00
}
]LIMIT 3 OFFSET 3 with envelope pagination metadata.{
“page”: 2,
“limit”: 3,
“total_records”: 124,
“total_pages”: 42,
“has_more”: true,
“data”: [
{
“id”: 301,
“title”: “Next.js Architecture Handbook”,
“price”: 15.00
}
]
}LIMIT, and prevents Out-of-Memory (OOM) crashes.4 HTTP Methods: CRUD, Safety & Idempotency Rules
Every HTTP request verb communicates precise operational semantics regarding resource mutation, safety guarantees, and idempotency repeatability under network retries.
| Method | CRUD Action | Endpoint Example | Safe? | Idempotent? |
|---|---|---|---|---|
| GET | Read / Retrieve | GET /api/v1/products/123 | ✅ Safe | ✅ Idempotent |
| POST | Create / Action | POST /api/v1/products | ❌ Unsafe | ❌ Non-Idempotent |
| PUT | Update (Full Replace) | PUT /api/v1/products/123 | ❌ Unsafe | ✅ Idempotent |
| PATCH | Update (Partial) | PATCH /api/v1/products/123 | ❌ Unsafe | ❌ Non-Idempotent* |
| DELETE | Delete / Destroy | DELETE /api/v1/products/123 | ❌ Unsafe | ✅ Idempotent |
Safe Methods are strictly read-only and guarantee zero server-side state mutation. Clients can pre-fetch, cache, and execute them unconditionally (e.g., GET, HEAD, OPTIONS).
Idempotent Methods produce the exact same server state whether executed 1 time or repeated 1,000 times ($f(f(x)) = f(x)$). Crucial for safe automatic network retries during network timeouts (e.g., PUT, DELETE, GET).
5 HTTP Status Codes & Standardized Error Handling
Well-engineered REST APIs communicate operational outcomes using standardized 3-digit HTTP status codes. Avoid returning 200 OK with an embedded error payload.
Location header).Retry-After header).{
“type”: “https://api.example.com/errors/insufficient-inventory”,
“title”: “Insufficient Inventory”,
“status”: 422,
“detail”: “Product 101 only has 2 items in stock, but 5 were requested.”,
“instance”: “/orders/checkout/req_9874”,
“invalid_params”: [
{
“name”: “quantity”,
“reason”: “Quantity requested exceeds available stock”
}
]
}6 API Design Best Practices: Anti-Patterns vs. REST Standards
/users, /orders)./products/123/reviews)./api/v1/…) to ensure backward compatibility.⚖️ Direct Comparison: Anti-Patterns vs. RESTful Standards
| ❌ Poor API Design (Anti-Pattern) | ✅ Good API Design (RESTful Standard) |
|---|---|
GET /getUser/123 ⚠️ Anti-Pattern: Action verb embedded in URI path + singular noun. | GET /api/v1/users/123 ✅ REST: Standard HTTP GET verb targeting plural collection with version. |
POST /users/123/delete ⚠️ Anti-Pattern: RPC-style method disguised inside a POST request. | DELETE /api/v1/users/123 ✅ REST: Idempotent HTTP DELETE method on target resource identifier. |
GET /products (returning 50,000 items) ⚠️ Anti-Pattern: Unbounded full-table database dumps risking server OOM. | GET /api/v1/products?page=1&limit=25&sort=price:asc ✅ REST: Bounded pagination envelope with explicit limits and sorting. |
HTTP 200 OK { “error”: “Not found” } ⚠️ Anti-Pattern: Masking failures under 200 OK breaks CDN caching and clients. | HTTP 404 Not Found { “title”: “User not found” } ✅ REST: Standardized status codes conforming to RFC 7807 problem details. |