RESTful API Design Questions

Direct answer. Model Book as the primary collection and Review as a resource nested under it, since a review's identity is meaningfully scoped to the book it is about, and shape the list-with-reviews response to avoid an N+1 by embedding a bounded preview rather than forcing a separate request per book.

The endpoint set.

Avoiding N+1 on the list endpoint. A naive implementation of GET /books that also wants to show "average rating" or "review count" per book would run one extra query PER book in the returned page, which is the classic N+1 pattern. The fix is to compute those aggregate fields with a single query joined or grouped across the whole page of books at once (one SQL query returning book rows with their review counts pre-aggregated), not a per-book follow-up call; if the client needs the actual review TEXT (not just a count), that stays on the separate /books/{bookId}/reviews endpoint entirely, rather than being embedded in the list response at all, since embedding full review bodies for every book on a list page is exactly the kind of over-fetching a list view does not need. Concretely, for a page of 20 books, the naive approach costs 1 query for the books plus 20 individual per-book count queries -- 21 queries total; the single joined/grouped query described above returns that same page of books with their review counts pre-aggregated in exactly 1 query, regardless of how many books are on the page.

Pagination on the nested collection. GET /books/{bookId}/reviews paginates independently of the parent books list, using the same offset-style ?page=/?limit= convention already shown above for GET /books (so GET /books/42/reviews?page=2&limit=20 is a perfectly ordinary request); a request for page 2 of one book's reviews has nothing to do with which page of the books list the client is currently viewing, since these are two independent, differently-scoped lists.

Trade-offs and pitfalls. The mistake this design avoids is either the fully-flat alternative (a top-level /reviews collection with no book scoping, forcing every client to filter by book_id as a query parameter for what is fundamentally always a book-scoped operation) or the fully-embedded alternative (returning every review inline inside every book response, which explodes payload size the moment a popular book accumulates thousands of reviews); nesting the reviews endpoint under its book, while keeping it as its own independently-paginated resource, is the middle ground that fits how this data is actually used.

Direct answer. REST for the public partner API (broad client reach, cacheability, and simplicity matter most and you cannot control what partners' HTTP tooling supports); gRPC for the internal high-throughput service mesh (binary framing, streaming, and generated strongly-typed clients matter more than human-readability once every caller is a service you control); and REST, or GraphQL if the client genuinely needs to shape a nested response itself, for the unreliable mobile client, prioritizing tolerance of dropped connections and minimizing round trips over raw throughput.

Comparison across the five axes.

• Caching: REST's biggest structural advantage. A GET request maps naturally onto HTTP caching (Cache-Control, ETag, CDN edge caching) because the URL itself identifies the cacheable resource. GraphQL's single POST-based endpoint and gRPC's binary RPC calls both defeat generic HTTP caching by default; both need a purpose-built caching layer if they want it at all.
• Client flexibility: GraphQL wins outright, since the client specifies exactly which fields it wants in one round trip; REST either over-fetches (returns the whole resource) or requires bespoke ?fields= parameters per endpoint; gRPC returns whatever the fixed protobuf schema defines, no client-side shaping at all.
• Network overhead: gRPC wins, using compact binary Protocol Buffers (a binary message format — smaller on the wire and faster for both sides to parse than text-based JSON, at the cost of not being readable directly in a browser's network tab) over HTTP/2 multiplexing (many requests and responses share one underlying connection at the same time, instead of the client opening a new connection per request); REST and GraphQL both typically ship JSON, which is larger and slower to parse, though GraphQL's field-selection can reduce payload size by avoiding over-fetch even with the same wire format.
• Versioning: REST has the most established conventions (URI/header/media-type, well understood by every client). GraphQL favors additive, non-breaking schema evolution with field deprecation over versioned endpoints entirely. gRPC's protobuf has strict, well-defined field-numbering rules for safe evolution, but breaking those rules (reusing a field number) is a hard, occasionally very difficult to detect production bug.
• Developer ergonomics: REST is the lowest common denominator, understood by literally every HTTP client, browser dev tool, and API testing tool with zero extra tooling. GraphQL and gRPC both need generated client code or specialized tooling to get real ergonomic benefit, which is friction for a public partner integration but a non-issue for an internal service mesh where every caller already runs your codegen pipeline (codegen — client-side code automatically generated from the service's schema, rather than hand-written by each team calling it).

Applying this to the three scenarios. A public partner API optimizes for the lowest integration cost for partners you do not control and for free CDN caching; REST wins on both. An internal high-throughput mesh optimizes for raw efficiency between services you fully control and can codegen against; gRPC wins. A mobile client on unreliable networks optimizes for minimizing round trips and tolerating partial failure; either a well-designed REST API with sparse fieldsets (a ?fields= query parameter letting the client name only the fields it actually needs back, so the server skips returning the rest of the resource), or GraphQL if the client's data needs are genuinely nested and variable screen-to-screen, both beat a chattier multi-call REST design, and gRPC's lack of native browser/mobile-friendly tooling (without a gRPC-Web proxy layer — an extra translation service that sits in front of gRPC, since a browser cannot speak raw HTTP/2 gRPC directly) makes it the weakest fit here despite its raw efficiency.

Trade-offs and pitfalls. The mistake to avoid is picking one paradigm company-wide "for consistency"; the three scenarios above genuinely optimize for different things, and a mesh forced into REST-for-consistency pays a real latency and serialization cost with no corresponding benefit, just as a public API built in gRPC for consistency loses the free caching and universal client support that made REST the right call there.

Direct answer. Use plural nouns for collections (/users, not /user), nest a resource under its parent only when it genuinely cannot exist independently of that parent (/users/{userId}/orders, since an order without a user makes no sense in this domain), and never encode an action as a verb in the path (no /getUser or /createOrder); if an operation is not naturally CRUD-shaped, model it as a sub-resource or an explicit action endpoint under the resource it acts on, not a bare verb.

Plural vs. singular. Plural nouns for every collection endpoint, consistently, even for a resource that will usually only ever have one instance per parent (a user's single /profile is a defensible, deliberate exception, since it genuinely is not a collection); consistency here matters more than any individual argument for singular naming, since an API mixing /users and /order for no principled reason forces every client developer to memorize which convention applies where.

When to nest, and when not to. Nest when the child resource's identity is meaningless without the parent (a specific order's line items only make sense scoped to that order: /orders/{orderId}/items) and the child is always accessed IN that context. Do NOT nest when the resource has its own independent identity and is commonly accessed on its own (a specific order is meaningfully addressable as /orders/{orderId} directly, even though it also appears as one entry under /users/{userId}/orders); over-nesting (/users/{userId}/orders/{orderId}/items/{itemId}/reviews/{reviewId}) makes URLs unwieldy and couples every deep resource's addressability to knowing its entire ancestor chain, when a flatter /reviews/{reviewId} with the relationship expressed in the response body would serve most clients better.

Actions that are not plain CRUD. For a genuine action (cancel this order, publish this post), prefer a sub-resource action endpoint (POST /orders/{id}/cancel) over inventing a new HTTP verb or falling back to an RPC-style bare verb in the path; this keeps the resource-oriented structure while still allowing operations that do not map cleanly onto GET/PUT/PATCH/DELETE.

Avoiding endpoint explosion as relationships grow. As a domain accumulates more relationships (users have orders, orders have items, items have reviews, reviews have replies...), resist nesting every single one; instead, expose the DEEPLY nested resources at their own flat, top-level path (/reviews/{reviewId}, not /users/{userId}/orders/{orderId}/items/{itemId}/reviews/{reviewId}) and use query parameters or embedded links to express the parent relationship, rather than growing the URL structure to mirror the full entity-relationship diagram.

Trade-offs and pitfalls. The most common mistake is treating nesting depth as free; each additional level of nesting is a small but real tax on every client that has to construct or parse that URL, and a domain's relationships almost always grow faster than anyone expects when the API was first designed.

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. Statelessness means every request must carry everything the server needs to process it: authentication, the resource being addressed, any filters or pagination position. The server is not allowed to remember what this client was doing between one request and the next. It is allowed to hold state about a resource (a row in a database), just not state about a specific client's conversation.

What it forbids, concretely. The classic violation is a login session: request 1 authenticates and the server stores "this session id is now logged in as user 42" in server memory; request 2 arrives with only the session id and the server looks up who that is from its own memory. That is exactly the per-client conversational state statelessness prohibits, because it means request 2 can only be served correctly by the specific server instance that handled request 1.

Two techniques that avoid it.

1. Signed, self-contained tokens (e.g. a JSON Web Token, JWT). The client presents a token on every request; the server verifies its signature and reads the user identity and permissions directly out of the token, with no server-side lookup of who this session is. Any server instance can validate any request with only its own signing key, which is what makes statelessness pay off: you can add or remove instances freely.
2. A session id backed by a shared, external store (for example Redis). The server still looks up session data, but the data lives outside any one instance's memory, so any instance can serve any request by querying the shared store. This is a middle ground: it is stateless from the server instance's point of view, even though state still exists somewhere.

What you get, and what you give up, when traffic spikes. With true statelessness (technique 1), you can add ten more instances behind a load balancer during a spike and route any incoming request to any of them, with zero coordination needed between instances, and you can kill an unhealthy instance immediately without worrying about losing anyone's conversation. What you give up: revocation is harder (a signed token is valid until it expires; you cannot instantly invalidate one without an extra deny-list mechanism), and the token itself grows with however much identity or permission data it carries, adding a small amount of bytes to every single request.

Trade-offs and pitfalls. Teams often reach for the shared-store approach (technique 2) because it feels like a smaller change from an in-memory session, but it quietly reintroduces a single dependency every request now needs, and if that store is slow or down, every request is affected, which is a different failure mode than the server that happened to hold your session being down.