RESTful API Design Questions

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. Malformed JSON is 400 Bad Request. A business-rule validation error is also 400 (or 422 Unprocessable Entity if you distinguish syntactically-valid-but-semantically-wrong from not-even-parseable). An authentication failure (no or invalid credentials) is 401 Unauthorized. An authorization failure (valid credentials, insufficient permission) is 403 Forbidden. A missing resource is 404 Not Found. Work accepted for asynchronous processing is 202 Accepted. A successful creation is 201 Created; a successful update with nothing new to return is 200 OK (or 204 No Content if the body is genuinely empty).

Working through the scenario.

1. Malformed JSON in the request body: the server never even got a well-formed request to evaluate, so this is a client error before any business logic runs. 400.
2. A validation error on a business rule (say, a date field that must not be in the past): the JSON parsed fine, but the content violates a rule. 400 is defensible; many APIs use 422 specifically to separate "your request is not even shaped right" from "your request is shaped right but the values are invalid." Pick one convention and apply it consistently across the whole API.
3. Authentication failure: 401, and the response should include a WWW-Authenticate header naming the expected scheme.
4. Authorization failure: 403. The distinction from 401 matters for the client: 401 means try again with different credentials, 403 means these credentials are fine, you just cannot do this.
5. Resource not found: 404. For a public API, be deliberate about whether a 404 for does-not-exist versus exists-but-you-cannot-see-it leaks information; many APIs intentionally return 404 for both to avoid confirming a private resource's existence to an unauthorized caller.
6. Accepted for async processing: 202, ideally with a Location header pointing at a status resource the client can poll.
7. Successful creation vs. update-with-nothing-new: 201 with the new resource's URI in Location for creation; 200 with a body, or 204 with no body, for an update, depending on whether you have anything useful to return.

Common mistake. Returning 200 for every successful outcome regardless of what actually happened, including creations (should be 201) and validation failures caught late in a handler (silently returning {"success": false} with a 200 status). This breaks every generic HTTP client, cache, and monitoring tool that reasons about status codes rather than parsing your custom body shape, and it is one of the most common REST code-review findings.

Trade-offs and pitfalls. 401 vs. 403 is the pair engineers mix up most: 401 always means I do not know who you are, or I do not believe your credentials; 403 always means I know exactly who you are, and the answer is still no.

Direct answer. Give each filterable field its own query parameter with an explicit, documented syntax (a range as min_price/max_price, a boolean as a plain true/false flag, an enum as a comma-separated allow-list, free text as a dedicated q parameter), and put sorting in a single sort parameter that names fields with an optional leading minus for descending order (sort=-created_at,price), rather than inventing a generic query language the client has to learn.

Concrete contract.

GET /products?category=electronics&min_price=20&max_price=200&in_stock=true&sort=-created_at,price&q=wireless

• category: exact-match enum, comma-separated for multiple values (category=electronics,books)
• min_price / max_price: a range filter as two separate parameters, not one combined string the server has to parse
• in_stock: a plain boolean flag
• sort: a comma-separated list of field names, a leading - meaning descending; the FIRST field is the primary sort key, later ones are tiebreakers
• q: a single free-text parameter for full-text search, kept separate from the structured filters above so the two can be combined without ambiguity about which is which

Why this stays discoverable and unambiguous. Each parameter maps to exactly one concept and one value shape; a client (or someone reading a URL in a support ticket) can tell what the request means without needing your API's full documentation open. The alternative, a single opaque filter=... string encoding a small query language, is more powerful but requires the client to learn a syntax; reserve that only if you genuinely need boolean combinations (AND/OR/NOT across arbitrary fields) that a flat parameter list cannot express, which most product-list endpoints do not.

Guarding against expensive ad-hoc queries. Three concrete guardrails: (1) a hard cap on how many fields can appear in sort at once (say, three), since each additional sort key can force the database into a more expensive multi-column sort if there is no index that matches the exact combination; (2) an explicit ALLOW-LIST of filterable and sortable fields, rejecting (400) any parameter name not on the list, rather than silently accepting and ignoring an unsupported one, which hides a client bug; (3) for the free-text q parameter specifically, route it to a purpose-built search index (not a live LIKE '%term%' scan of the primary table), since unindexed free-text search is exactly the kind of client-constructed query that degrades everyone else's performance the moment the dataset is large.

Trade-offs and pitfalls. The most common mistake is exposing every column in the underlying table as a filterable parameter "for flexibility", which both makes the API's real contract unclear (nothing distinguishes an intentionally-supported filter from an accidentally-exposed internal column) and means a client can construct a filter/sort combination with no supporting index, turning an innocent-looking request into a full table scan.

Direct answer. For a public B2B API with many long-lived client integrations, default to URI-path versioning (/v1/, /v2/), because it is the most discoverable and the most compatible with the widest range of client tooling, proxies, and caches; header-based versioning is a legitimate alternative when you specifically want version selection to be invisible in the URL, at the cost of being harder for a developer to discover just by looking at a request.

URI-path versioning (/v1/users). Maximally discoverable (a developer can see the version in every request and every piece of documentation without inspecting headers), trivially cacheable (the version is part of the cache key automatically, since it is part of the URL), and compatible with every HTTP client, proxy, and browser address bar without special support. The downside: it implies the ENTIRE API surface moves in lockstep between versions, which is not always true (often only a handful of endpoints actually changed), and "the same resource lives at two different URLs" can feel philosophically at odds with REST's idea that a URI identifies one resource.

Header-based versioning (Accept: application/vnd.myapi.v2+json). Keeps the URL itself stable across versions, which is arguably more RESTfully "correct" (the resource's identity does not change just because its representation format evolved) and lets you version different resources independently if you choose to. The cost: it is invisible to a quick glance at a URL, harder to test by pasting a URL into a browser, and it interacts poorly with caches and proxies that key on the URL alone and are not configured to also vary on this custom header (the response needs an explicit Vary header naming it, and not every intermediate cache respects that correctly).

Query-parameter versioning (?version=1). The weakest of the three in practice: it is easy to omit accidentally (defaulting to whatever the server picks, silently, if the developer forgets the parameter) and it does not compose cleanly with caching or with existing query parameters used for filtering, since a cache or proxy has to know that THIS particular parameter, unlike most others, actually changes the shape of the response entirely.

Why URI-path for THIS specific scenario. Many long-lived integrations means you will realistically be running two or three versions concurrently for a long time, and you want every one of those integrator teams to be able to look at their own code, or a support ticket's request log, and see immediately which version they are on, without any header inspection; that discoverability benefit outweighs the philosophical purity argument for header-based versioning once the number of long-lived external client teams gets large.

Trade-offs and pitfalls. Whichever mechanism you pick, the mistake that causes real pain later is not deciding it up front and mixing conventions ad hoc across endpoints as they evolve; a client integrating against your API should never have to learn a second versioning convention for a different endpoint of the same API.

Direct answer. All four endpoints violate resource-based conventions by putting a verb or an ambiguous shape in the path where a noun-and-HTTP-method combination should carry that meaning instead.

1) GET /getUser?id=123 -> GET /users/123. The verb "get" in the path is entirely redundant: the HTTP method GET already says "read," and the path should just identify the resource (a specific user) as a noun with its id as a path parameter, not a query parameter, since the id is not an optional filter, it is the resource's own identity.

2) POST /user/create -> POST /users. Two problems: the "create" verb is redundant (POST to a collection already conventionally means "create a new member of it"), and the resource noun is singular ("user") when it should be the plural collection ("users") being posted into.

3) GET /v1/get-all-books -> GET /v1/books. Same redundant-verb problem ("get-all"), plus the hyphenated multi-word verb phrase compounds it; a plain plural collection name, with GET as the method, already communicates "list all books" without any verb needed in the path at all.

4) /accounts/123/transactions?start=... -> mostly fine already, worth keeping as GET /accounts/123/transactions?start=...&end=.... This one is actually a reasonably good example of RESTful nesting (a transaction genuinely belongs to and is scoped by its account) with query parameters correctly used for a date-range FILTER rather than for identifying the resource itself; the only real gap is that the HTTP method was left unstated in the original, which matters, since the same path could describe either GET (list transactions) or, if this were a POST, something entirely different (create a transaction) with no way to tell from the URL shape alone.

Why these choices, generally. Pluralization is applied consistently to every collection (users, books), never mixed with singular naming for no reason. Nesting is used only where 4) already earns it (a transaction genuinely belongs to one account) and not forced onto the others, which do not have an obvious required parent. Query parameters are reserved for filtering, sorting, and pagination (as in the date-range example), never for identifying WHICH resource a request is about, which belongs in the path as in the /users/123 fix.

Trade-offs and pitfalls. The most common residual mistake even after fixing the obvious verbs is to leave query parameters doing double duty (both filtering AND identifying a resource), which example 1's original design did by putting the user's own id in a query parameter instead of the path; a resource's own identity always belongs in the path, never in a query string.