RESTful API Design Questions

Direct answer. HATEOAS (Hypermedia As The Engine Of Application State) means a response includes links describing what the client can legitimately do next from this resource's current state, so the client does not need to hard-code which endpoints exist or which transitions are valid; it follows links the server hands it.

Worked example. For an order in the "pending" state:

{
  "id": "ord_123",
  "status": "pending",
  "total": 4200,
  "_links": {
    "self": { "href": "/orders/ord_123" },
    "items": { "href": "/orders/ord_123/items", "method": "GET" },
    "pay":  { "href": "/orders/ord_123/pay", "method": "POST" },
    "cancel": { "href": "/orders/ord_123/cancel", "method": "POST" }
  }
}

The items link is a plain GET that stays present regardless of the order's state, since viewing the line items is never a state-dependent action, unlike pay and cancel, which only appear while the order is actually in a state where they are legal.

Once the order is paid, the server's next response for that same order would include a "ship" link and drop "pay" and "cancel" entirely. The client does not need business logic hard-coded like show a pay button only when status is pending; it just renders whatever links are present.

What this actually buys you. The client-server coupling gets looser in one specific way: valid-transition logic lives on the server, not duplicated in every client. If the business rule for when an order can be cancelled changes (say, cancellation is disabled once payment starts processing, not just once it succeeds), you change it in one place on the server, and every client (web, mobile, a partner's integration) picks up the new behavior automatically the next time they fetch the resource, because the cancel link simply stops appearing rather than each client needing an updated copy of the rule.

Why most public APIs skip it anyway. The honest reason is that hypermedia adds real client-side complexity (parsing and following links instead of calling a URL your team already documented and your SDK already hard-codes) for a benefit that mostly matters when you have many independent, evolving clients that cannot easily be updated in lockstep. Most companies' actual API consumers are their own web and mobile apps, deployed together with the backend, so the decoupling benefit is smaller than it sounds, and clients overwhelmingly prefer a documented, predictable URL they can call directly over a discovery protocol they have to implement. Full HATEOAS survives mostly in specs and prep material, not in most production public APIs, precisely because the cost (client complexity, harder caching of what actions exist) is paid up front while the benefit only shows up much later, if ever.

Trade-offs and pitfalls. Treat HATEOAS as a genuine trade-off you can articulate, not a rule you are expected to follow: if your API has one first-party client you control end-to-end, the coupling HATEOAS avoids barely exists in the first place.

Direct answer. Put a single translation layer between "whatever actually broke internally" and "what the client sees," so every internal exception passes through one place that decides the client-facing status code and message, rather than letting internal error text leak out through whichever handler happened to catch it.

The translation layer's job. Catch exceptions at the boundary (a global exception handler, or a dedicated error-mapping function every route calls into), and for each KNOWN category of internal failure, map it to a specific, safe, client-facing error: a database unique-constraint violation becomes a 409 Conflict with a generic "this resource already exists" message, not the raw constraint name and table structure; an internal service timeout becomes a 503 with a retryable flag, not the internal service's hostname or the exact RPC that failed; anything UNRECOGNIZED (a genuine bug, not a known failure category) becomes a generic 500 with no detail beyond a correlation id, specifically because an unrecognized exception is the one case where you cannot be confident that its message does not accidentally contain something sensitive (a query with embedded user data, a file path, a partial credential).

Preserving the real error for debugging. The translation layer logs the FULL original exception (stack trace, internal service name, the real error text) server-side, tagged with the same correlation id that goes back to the client in the sanitized response. An SRE or engineer investigating an incident looks up that correlation id in the logs and gets everything; the client only ever sees the generic, safe version plus that same id to hand back for support.

Why an allow-list of known mappings, not a deny-list of things to strip. Trying to scrub specific sensitive PATTERNS out of an arbitrary internal error message (strip anything that looks like a file path, strip anything that looks like a hostname) is a losing game against an internal system that can produce arbitrarily-shaped error text; the safe default has to be "unless this exception is on our known, reviewed list, the client gets a generic message," not "leak everything except what we thought to filter."

Trade-offs and pitfalls. The most common near-miss is mapping the KNOWN error categories correctly but forgetting that a catch-all handler for UNKNOWN exceptions defaults to including the exception's own message in the response "to help debugging," which reintroduces exactly the leakage this whole layer exists to prevent, the first time an unanticipated internal error happens to contain something sensitive.

Direct answer. GET, HEAD, and OPTIONS are safe (they must not change server state) and idempotent (calling them N times has the same effect as calling them once). PUT and DELETE are idempotent but not safe. POST is neither safe nor idempotent by default. PATCH is technically unspecified but should usually be treated as non-idempotent unless you deliberately design it to be. Cacheability tracks safety closely but is not identical to it: GET and HEAD are cacheable by default, OPTIONS is safe but has no real caching convention, and none of PUT, DELETE, POST, or PATCH are cacheable by default.

The full classification.

Why cacheability does not just follow safety. GET and HEAD are cacheable by default because a cache can reuse their response without risking a stale side effect, the same property that makes them safe in the first place. OPTIONS is also safe, but nothing about discovering allowed methods or a CORS preflight benefits from caching the way a resource representation does, so there is no real caching convention for it in practice. POST responses CAN technically be cached per the HTTP spec if the response carries explicit freshness information (Cache-Control or Expires), but this is rarely implemented, so treat POST as effectively not cacheable. PUT, DELETE, and PATCH have no meaningful default caching semantics either: caching the result of a mutation makes little sense when the whole point of the call was to change state.

Why this matters beyond vocabulary. Idempotency is the property that makes retries safe. If a client's network call to a PUT times out and it retries, the end state is identical whether the first request actually landed or not, because PUT is defined as "the resource now looks like this", not "apply this delta". A POST retried the same way can create two resources, because POST means "do this action again", and doing a creation action twice creates two things. Safety is what a cache, a browser prefetcher, or a crawler relies on: none of them should ever issue a POST speculatively, because a safe method is one where the caller assumes no side effect happened.

A real bug from getting this wrong. A checkout flow implemented "add item to cart" as a GET request (because it was convenient to trigger from a link). A corporate web-security scanner crawled every link on the page, including that one, adding dozens of items to real users' carts, because the scanner (correctly, per the HTTP contract) assumed GET was safe to call without consequence. The fix was not to block the scanner, it was to make cart mutation a POST, which is exactly what the safety property exists to protect against.

Trade-offs and pitfalls. The subtlest mistake is assuming PATCH is idempotent by default. A PATCH body of {"counter": "increment"} is not idempotent (retrying it increments twice); a PATCH body of {"counter": 5} (set to an absolute value) is. The method name alone does not tell a client which one they are getting, so this needs to be documented per endpoint, not assumed from the HTTP verb.

Direct answer. Model the lifecycle transitions as explicit sub-resource action endpoints (POST /orders/{id}/ship, POST /orders/{id}/cancel) rather than a bare PATCH to a status field, because the action endpoints let the server enforce which transitions are even valid from the current state and give each transition its own place to carry transition-specific side effects, at the cost of one extra endpoint per transition compared to a single generic PATCH.

Action endpoints vs. a generic status PATCH. PATCH /orders/{id} {"status": "shipped"} is compact and reuses the uniform PATCH verb, but it pushes ALL the validation logic ("is this transition even legal from the current state? does shipping require a carrier and tracking number to be provided at the same time?") into a single generic handler that has to branch internally on every possible status value, and it makes it awkward to require different REQUEST BODIES for different transitions (shipping needs a tracking number; cancelling needs a reason code). Explicit action endpoints (POST /orders/{id}/ship with a {tracking_number} body, POST /orders/{id}/cancel with a {reason} body) let each transition define its own contract naturally, and let the URL itself communicate intent to a developer reading an access log, rather than requiring them to inspect the request body to know what actually happened.

Handling an invalid transition attempt. A client calling POST /orders/{id}/cancel on an order that has already shipped should get 409 Conflict (the request is well-formed, but the resource's current state makes this specific transition illegal), with a response body naming both the attempted transition and the order's actual current state, so the client can show a useful message rather than a bare error code. This is meaningfully different from a 400 (which would suggest the REQUEST itself was malformed) or a 404 (the order does exist, this transition on it is simply not allowed right now).

Discoverability and URL complexity. Action endpoints add one URL per transition (ship, cancel, and any future ones like "refund" or "return"), which is a real but bounded and predictable cost, versus a single generic PATCH endpoint whose full behavior is invisible from the URL alone and only discoverable by reading documentation or the request body's field values. For an order lifecycle with a small, stable set of transitions, the discoverability benefit of one clearly-named endpoint per transition outweighs the modest URL-count cost.

Trade-offs and pitfalls. The most common mistake is mixing the two approaches inconsistently (some transitions as actions, others folded into a generic PATCH "for convenience"), which forces every client to learn two different conventions for what is conceptually the same kind of operation across the same resource.

Direct answer. Offset pagination (?page=3&page_size=20) is the simplest to implement and the worst under change: it skips or repeats rows when data is inserted or deleted between page requests, and gets slower the deeper you page because the database still has to count past all the skipped rows. Cursor (keyset) pagination anchors each page on the last row you actually saw, so it stays correct under churn and stays fast at any depth, at the cost of losing the ability to jump straight to page 40.

Why offset breaks under churn. If a new row is inserted at the front of the sorted list while a client is between page 1 and page 2, everything shifts by one position: the client's page 2 request (offset=20) now returns a row it already saw on page 1, and misses the row that got pushed off the end. Nothing is wrong with the server, the math of "skip N rows" simply assumes the set of rows is frozen, which it never is in a live system.

Why cursor pagination does not have this problem. Instead of saying "skip 20 rows", a cursor request says "give me rows that sort after THIS specific row I already saw" (typically encoded as the last row's sort key plus its id, to break ties). New rows inserted anywhere other than exactly at that boundary do not shift anyone's position relative to a cursor they already hold, because the cursor is anchored to real data, not a row count.

Performance at depth. Offset pagination on page 10,000 still has to have the database walk past (or index-skip) the first 200,000 rows before it can return row 200,001; that cost grows with the offset. A cursor query uses an index seek directly to the anchor position and returns the next page from there, so page 10,000 costs roughly the same as page 1.

When offset is still the right choice anyway. An admin UI where someone genuinely wants to jump to "page 40" by number, or a small, rarely-changing dataset where churn is not a real concern, is a legitimate reason to keep offset pagination: cursor pagination cannot support random access to an arbitrary page number, only "next" and "previous" relative to where you are.