REST API Design Checklist

A practical reference covering every decision point when designing a REST API — from URL structure and HTTP semantics to versioning, pagination, and error shapes. Use this as a review checklist before shipping.

Resource URL Structure

Follow these rules for every endpoint you design:

# Collections — plural nouns
GET    /users              # list all users
POST   /users              # create a new user

# Specific resource — ID in path segment
GET    /users/42           # get user 42
PUT    /users/42           # full replace
PATCH  /users/42           # partial update
DELETE /users/42           # delete

# Nested resource (max 2 levels)
GET    /users/42/orders    # orders belonging to user 42
GET    /users/42/orders/7  # specific order for user 42

# WRONG — verbs in URL
POST   /createUser         # bad
GET    /users/getAll       # bad
POST   /users/42/delete    # bad

HTTP Method Semantics

*PATCH is only idempotent if using JSON Patch format (RFC 6902). Merge-patch operations are not guaranteed idempotent.

Status Code Quick Reference

200 OK              — Successful GET, PUT, PATCH with response body
201 Created         — Successful POST; include Location: /users/42
204 No Content      — Successful DELETE or PUT/PATCH with no body
304 Not Modified    — GET with conditional If-None-Match / If-Modified-Since
400 Bad Request     — Malformed JSON, wrong types, missing required fields
401 Unauthorized    — No auth token, expired token, invalid signature
403 Forbidden       — Valid token but insufficient permissions
404 Not Found       — Resource does not exist (or hidden for security)
405 Method Not Allowed — PUT on a collection, etc.
409 Conflict        — Duplicate unique field, optimistic lock version mismatch
410 Gone            — Resource permanently deleted (use over 404 for caching)
422 Unprocessable   — Syntactically valid but semantically wrong (validation)
429 Too Many Requests — Rate limited; include Retry-After header
500 Internal Error  — Server-side failure; return trace_id, log full error
503 Service Unavailable — Dependency down; include Retry-After header

Filtering, Sorting & Pagination

# Filtering — query params per field
GET /orders?status=pending&created_after=2024-01-01

# Range filters with operators
GET /products?price[gte]=10&price[lte]=100
GET /products?price_min=10&price_max=100  # simpler alternative

# Sorting — comma-separated, prefix minus for desc
GET /users?sort=-created_at,name    # newest first, then by name asc

# Cursor pagination (recommended for large data)
GET /posts?limit=20
# Response includes:
# { "data": [...], "meta": { "next_cursor": "eyJpZCI6MjB9", "has_more": true } }
GET /posts?cursor=eyJpZCI6MjB9&limit=20

# Field selection (sparse fieldsets)
GET /users?fields=id,name,email     # only return requested fields

Consistent Error Response Shape

// 422 Validation error
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "issue": "must be a valid email address" },
      { "field": "age",   "issue": "must be a positive integer" }
    ],
    "trace_id": "req_01hxyz..."
  }
}

// 404 Not found
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user found with id 42",
    "trace_id": "req_01habc..."
  }
}

// 429 Rate limited
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 30
  }
}
// Also set headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

Versioning Strategy

# Option 1: URL versioning (most common, cache-friendly)
GET /v1/users
GET /v2/users

# Option 2: Request header versioning
GET /users
X-API-Version: 2

# Option 3: Content-type negotiation (RFC 6838)
Accept: application/vnd.myapi.v2+json

# Deprecation lifecycle headers
Deprecation: Tue, 01 Jan 2025 00:00:00 GMT
Sunset: Mon, 01 Jul 2025 00:00:00 GMT
Link: <https://devdocs.example.com/v2/migration>; rel="successor-version"

HATEOAS Basics

// Minimal HATEOAS — self link + available actions
{
  "id": 42,
  "status": "pending",
  "total": 199.99,
  "_links": {
    "self":    { "href": "/orders/42",        "method": "GET" },
    "cancel":  { "href": "/orders/42/cancel", "method": "POST" },
    "invoice": { "href": "/orders/42/invoice","method": "GET" }
  }
}

// Paginated collection with navigation links
{
  "data": [...],
  "_links": {
    "self":  { "href": "/posts?page=3" },
    "next":  { "href": "/posts?page=4" },
    "prev":  { "href": "/posts?page=2" },
    "first": { "href": "/posts?page=1" },
    "last":  { "href": "/posts?page=12" }
  },
  "meta": { "total": 234, "per_page": 20 }
}

Pre-Ship Checklist