API Design: REST Principles & URLs

REST (Representational State Transfer) is an architectural style for designing networked APIs. A well-designed REST API is intuitive, consistent, and predictable.

REST Constraints

• Client-Server: UI and data storage concerns are separated — client doesn't know how data is stored

• Stateless: every request contains all information needed — no server-side session state

• Cacheable: responses should indicate whether they can be cached (Cache-Control headers)

• Uniform Interface: consistent resource identification, manipulation through representations, self-descriptive messages, HATEOAS

• Layered System: client doesn't know if it's talking to the real server or a proxy/CDN

URL Design

# Resources are nouns, not verbs
❌ GET /getUsers
❌ POST /createUser
✅ GET /users
✅ POST /users

# Hierarchical relationships
GET    /users                    — list all users
POST   /users                    — create a user
GET    /users/{id}               — get one user
PUT    /users/{id}               — replace user (full update)
PATCH  /users/{id}               — partial update
DELETE /users/{id}               — delete user

# Nested resources (use sparingly — max 2 levels deep)
GET  /users/{id}/orders          — user's orders
GET  /users/{id}/orders/{oid}    — specific order
POST /users/{id}/orders          — create order for user

# Actions that don't map to CRUD (use sub-resource or POST)
POST /users/{id}/activate        — activate user
POST /orders/{id}/cancel         — cancel order
POST /emails/send                — send email (not a resource but an action)

HTTP Methods & Idempotency

Method   Idempotent  Safe   Use for
GET      ✅           ✅     Retrieve resource(s)
POST     ❌           ❌     Create resource, trigger action
PUT      ✅           ❌     Replace resource entirely
PATCH    ❌*          ❌     Partial update
DELETE   ✅           ❌     Remove resource
HEAD     ✅           ✅     GET without body (check existence)
OPTIONS  ✅           ✅     CORS preflight, list allowed methods

* PATCH can be made idempotent depending on implementation

Idempotent = calling N times has same result as calling once
Safe = does not modify state

HTTP Status Codes

2xx — Success
  200 OK              — GET success, PATCH/PUT success
  201 Created         — POST success; include Location header with new resource URL
  204 No Content      — DELETE success, PATCH with no body to return

4xx — Client Errors
  400 Bad Request     — malformed JSON, invalid params, validation error
  401 Unauthorized    — not authenticated (wrong/missing token)
  403 Forbidden       — authenticated but not authorized (right token, wrong role)
  404 Not Found       — resource doesn't exist
  409 Conflict        — duplicate resource, optimistic locking conflict
  410 Gone            — permanently deleted (stronger than 404)
  422 Unprocessable   — valid JSON but failed domain validation (preferred over 400 for validation)
  429 Too Many Requests — rate limited; include Retry-After header

5xx — Server Errors
  500 Internal Server Error — unexpected failure
  502 Bad Gateway     — upstream service failed
  503 Service Unavailable — maintenance, overload; include Retry-After