API Design

Key features

• A resource is a noun addressed by a URL (/orders/42) — the HTTP method supplies the verb, so /getOrders or /deleteOrder/42 duplicates the verb the method already carries
• GET, PUT, DELETE and HEAD are idempotent by definition — calling them once or five times leaves the server in the same state; POST and PATCH are not, by default
• GET and HEAD are also safe — they must not change server state at all, which is what lets proxies and browsers cache or prefetch them freely
• 2xx means success (200 OK, 201 Created, 204 No Content); 4xx means the client's request was the problem (400 Bad Request, 401 Unauthenticated, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity); 5xx means the server failed even though the request was valid
• 201 Created should return a Location header pointing at the new resource's URL, rather than only a 200 with a body
• Idempotency (an operation is safe to retry without a second effect) matters most for POST, since PUT/DELETE already get it for free from the method definition — full idempotency-key mechanics are a separate concept

Command

GET    /orders          -- list orders
POST   /orders          -- create an order
GET    /orders/{id}     -- read one order
PUT    /orders/{id}     -- replace one order
PATCH  /orders/{id}     -- partially update one order
DELETE /orders/{id}     -- delete one order

Key features

• Pagination limits response size and server load — returning an unbounded collection risks timeouts, huge payloads and accidental full-table scans
• Filtering narrows a collection by field value, typically ?status=shipped or ?createdAfter=2026-01-01 — treat filter parameters as an AND unless the API explicitly documents OR semantics
• Sorting controls order, typically ?sort=-createdAt (a leading - for descending) or ?sort=field,-otherField for multiple keys
• Search (?q=blue+jacket) is a relevance-ranked text match, a fundamentally different operation from filtering — filtering is exact/range matching on structured fields, search is fuzzy matching on free text
• Combine them in one request rather than layering separate endpoints: GET /orders?status=shipped&sort=-createdAt&limit=20&cursor=abc123 is one coherent call, not four

Command

GET /orders?status=shipped        -- filter
GET /orders?sort=-createdAt        -- sort (- = descending)
GET /orders?q=blue+jacket          -- search
GET /orders?limit=20&cursor=abc    -- paginate

Key features

• Non-breaking changes need no version bump: adding an optional field, adding a new endpoint, adding a new optional query parameter, relaxing a validation rule
• Breaking changes need a version bump: removing or renaming a field, changing a field's type, changing what a status code means, tightening validation on existing input
• The three common versioning strategies: URL path (/v2/orders), a custom header (Api-Version: 2), or content negotiation (Accept: application/vnd.example.v2+json) — URL path is the most visible and the most common in practice
• A deprecation window (an old version keeps working, clearly marked deprecated, for a stated period) is what makes a breaking change survivable for existing clients — a version bump without one only moves the breaking change to a later, unannounced date
• Postel's robustness principle applies to API evolution too: a server should ignore fields it does not recognize in a request rather than rejecting the whole call, so adding a field never accidentally becomes a breaking change for old servers

Command

GET /v2/orders/42 HTTP/1.1              -- URL path versioning
GET /orders/42 HTTP/1.1
Api-Version: 2                            -- header versioning
GET /orders/42 HTTP/1.1
Accept: application/vnd.example.v2+json   -- content negotiation

Key features

• Offset pagination (LIMIT/OFFSET in SQL terms) is simple to implement and lets a client jump to an arbitrary page number, but a large offset gets slower — the database still has to scan and discard every skipped row
• Cursor pagination encodes a position (typically the last row's sort key, e.g. an id or timestamp) into an opaque token; the next request asks for rows after that cursor, so it never re-scans skipped rows
• Offset pagination is unsafe on a changing dataset: inserts or deletes before the current page shift every row's offset, causing a client to see a duplicate row or silently miss one between two page requests
• Cursor pagination cannot jump to an arbitrary page number (no "go to page 8") since a cursor only knows "after this specific row" — it is built for infinite-scroll and next-page navigation, not numbered pagination UI
• Offset pagination is the right default for small, mostly-static datasets with a numbered-page UI (an admin table with a few thousand rows); cursor pagination is the right default for large or frequently-changing datasets (a social feed, an event log, an API consumed by other services)

Command

GET /orders?limit=20&offset=40      -- offset pagination
GET /orders?limit=20&cursor=abc123   -- cursor pagination

Key features

• A stable identifier never changes for the life of the resource — using a mutable field (email, username, display name) as the primary identifier breaks every stored reference the moment that field is edited
• Surrogate keys (an auto-increment integer, a UUID) make good stable identifiers precisely because nothing about them is meaningful or expected to change; natural keys (email, SKU string) often turn out to need editing later
• An error contract needs a machine-readable code (e.g. "order_not_found"), separate from the human-readable message, so client code can switch on the code without string-matching prose that might get reworded
• A consistent error contract also needs a stable place for field-level validation errors (which field, what was wrong) — a client rendering a form cannot highlight the right input from a single flat message string
• RFC 7807 (Problem Details for HTTP APIs) is a standardized error shape — type, title, status, detail, instance — worth adopting or matching even if not used verbatim, so error handling is not reinvented per API

Command

{
  "error": {
    "code": "order_not_found",
    "message": "No order with id 9999",
    "requestId": "req_8f3a2b1c"
  }
}