REST Principles & HTTP Verbs

# ── REST URL design - nouns, not verbs ─────────────────────────

# ❌ RPC-style (not REST)
GET  /getPosts
POST /createPost
POST /updatePost/1
POST /deletePost/1

# ✅ RESTful - resource-based
GET    /api/v1/posts           → list all posts
POST   /api/v1/posts           → create a post
GET    /api/v1/posts/{id}      → get one post
PUT    /api/v1/posts/{id}      → replace entire post
PATCH  /api/v1/posts/{id}      → partial update
DELETE /api/v1/posts/{id}      → delete post

# Nested resources
GET    /api/v1/posts/{id}/comments     → comments for a post
POST   /api/v1/posts/{id}/comments     → add comment to post
DELETE /api/v1/posts/{id}/comments/{cid} → delete a comment

# ── HTTP Status Codes ──────────────────────────────────────────
# 2xx - Success
# 200 OK           - GET/PUT/PATCH successful, body returned
# 201 Created      - POST successful, new resource created
# 204 No Content   - DELETE/PUT successful, no body needed

# 3xx - Redirection
# 301 Moved Permanently - resource URL changed permanently
# 304 Not Modified      - cached response still valid (ETag match)

# 4xx - Client errors (caller did something wrong)
# 400 Bad Request       - invalid JSON, missing required field
# 401 Unauthorized      - no auth token, or token invalid
# 403 Forbidden         - authenticated but lacks permission
# 404 Not Found         - resource does not exist
# 405 Method Not Allowed - GET only, got POST
# 409 Conflict          - duplicate slug, unique constraint violation
# 422 Unprocessable     - structurally valid but fails validation
# 429 Too Many Requests - rate limit exceeded

# 5xx - Server errors (your code failed)
# 500 Internal Server Error - unexpected exception
# 502 Bad Gateway           - upstream service down
# 503 Service Unavailable   - maintenance or overload

# ── JSON:API response envelope ────────────────────────────────
# Standard response structure - consistent across all endpoints:
# {
#   "success": true,
#   "data": { ... },          ← single resource or array
#   "meta": { "total": 42 },  ← optional pagination, counts
#   "links": { "next": "..." } ← optional pagination links
# }
#
# Error response:
# {
#   "success": false,
#   "error": {
#     "code":    "VALIDATION_ERROR",
#     "message": "Validation failed",
#     "details": { "title": "Title is required." }
#   }
# }