REST Fundamentals

REST Fundamentals

REST is the standard architectural style for web APIs. It maps HTTP methods to CRUD operations on URL-named resources.

URL Design

Collection:  GET    /api/courses         → list all courses
             POST   /api/courses         → create a course

Single item: GET    /api/courses/:id     → get one course
             PATCH  /api/courses/:id     → update a course
             DELETE /api/courses/:id     → delete a course

Nested:      GET    /api/users/:id/progress  → user's progress
             POST   /api/users/:id/progress  → mark course complete

HTTP Methods

GET     → Read — safe, idempotent, no body
POST    → Create — not idempotent (creates new resource each time)
PUT     → Replace entire resource — idempotent
PATCH   → Partial update — send only changed fields
DELETE  → Remove — idempotent
HEAD    → Same as GET but no body — check existence/headers
OPTIONS → Describe allowed methods — used in CORS preflight

HTTP Status Codes

2xx Success:
  200 OK           — successful GET, PUT, PATCH
  201 Created      — successful POST
  204 No Content   — successful DELETE (no body)

4xx Client Error:
  400 Bad Request  — invalid request body
  401 Unauthorized — not authenticated
  403 Forbidden    — authenticated but no permission
  404 Not Found    — resource doesn't exist
  422 Unprocessable — validation error (correct format, wrong data)
  429 Too Many Requests — rate limited

5xx Server Error:
  500 Internal Server Error — unexpected error
  503 Service Unavailable   — server overloaded/down

REST vs Other Patterns

REST        — resource-based, HTTP verbs, flexible
GraphQL     — query language, single endpoint, specify exact fields
tRPC        — TypeScript-first RPC, end-to-end type safety, Next.js native