REST API Design Explained

REST is the dominant API style on the modern web. It’s not a protocol — it’s a set of conventions for using HTTP to expose resources. Originally defined by Roy Fielding’s 2000 dissertation, the strict definition is rarely followed today; what most APIs call “REST” is more accurately “HTTP APIs that follow common conventions.”

The core idea: resources, not actions

REST thinks in nouns (resources) and uses HTTP verbs to act on them. Compare:

BAD (RPC-style):
  POST /createUser
  POST /getUser
  POST /deleteUser

GOOD (REST-style):
  POST   /users           ← create
  GET    /users           ← list
  GET    /users/123       ← retrieve one
  PUT    /users/123       ← replace
  PATCH  /users/123       ← modify
  DELETE /users/123       ← remove

The 6 rules of REST conventions

1. URLs identify resources, not actions

Use nouns. Plural names for collections, IDs for individual resources. Nest related resources.

/users
/users/123
/users/123/posts
/users/123/posts/456

2. Use HTTP methods for the action

GET to read, POST to create, PUT/PATCH to update, DELETE to remove. Never tunnel actions through GET (e.g., GET /users/123/delete — wrong).

3. Use HTTP status codes correctly

Code	When
200 OK	Successful GET / PUT / PATCH / DELETE with body
201 Created	Successful POST that created a resource
204 No Content	Successful action with empty body
400 Bad Request	Malformed JSON, missing required field
401 Unauthorized	No / invalid auth token
403 Forbidden	Authenticated but not allowed
404 Not Found	Resource doesn’t exist
409 Conflict	Trying to create something that exists
422 Unprocessable Entity	Valid JSON but invalid business logic
429 Too Many Requests	Rate limited
500 Internal Server Error	Bug on your side
503 Service Unavailable	Overloaded or maintenance

4. Idempotency matters

Same request made multiple times should have the same effect. GET, PUT, DELETE are naturally idempotent. POST is not — if a network glitch causes a retry, you might create the resource twice.

Solution: idempotency keys. Client generates a unique key per logical operation; server stores it for some time and returns the cached response if the same key arrives twice.

5. Pagination, filtering, sorting in query strings

GET /users?page=2&per_page=50
GET /users?role=admin&status=active
GET /users?sort=created_at&order=desc

6. Versioning the API

Three common approaches:

• URL path: /v1/users (most common, easiest)
• Header: Accept: application/vnd.example.v2+json
• Query string: /users?api_version=2 (least preferred)

Authentication patterns

• API keys — simple, send in header: X-API-Key: abc123
• Bearer tokens — JWT or opaque, send: Authorization: Bearer eyJ...
• OAuth 2.0 — for third-party apps acting on user behalf
• HMAC signatures — AWS-style, sign each request with shared secret

Documentation and contracts

Describe your API with OpenAPI (formerly Swagger) — a YAML or JSON spec that documents endpoints, payloads, errors. Tools generate client libraries, mock servers, and interactive docs from it.

Common mistakes

• Using POST for everything (RPC-style instead of REST)
• Returning 200 OK with an error message in the body — use proper status codes
• Not versioning, then having to break compatibility later
• Forgetting idempotency keys for POSTs that create things
• Inconsistent naming (camelCase here, snake_case there)

What to learn next

WebSockets and Server-Sent Events — when REST isn’t enough and you need real-time bidirectional communication. Up next.