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." }
#   }
# }