REST API Interview Questions

Common REST API interview questions, from fundamentals through the design trade-offs that come up in system design rounds.

Q: What's the difference between REST and RPC-style APIs? REST models an API around resources (nouns) addressed by URLs, with a small, uniform set of HTTP methods (GET, POST, PUT, PATCH, DELETE) expressing actions on them. RPC ("Remote Procedure Call") style APIs model an API around actions (verbs) — endpoints like /getUser or /cancelOrder that read like function calls. Neither is strictly "better" — RPC (and its modern typed form, gRPC) often fits internal service-to-service calls well, while REST's uniform, resource-oriented interface tends to produce more predictable, cacheable public APIs.

Q: Is PUT idempotent? Is POST? PUT is idempotent — sending the same PUT request multiple times leaves the resource in the same end state as sending it once, because it replaces the resource with the given representation. POST is generally not idempotent — calling POST /orders twice with the same body typically creates two separate orders, since its purpose is "create a new thing inside this collection" each time it's called.

Q: What's the difference between offset-based and cursor-based pagination, and when would you choose each? Offset-based pagination (?offset=40&limit=20) is simple and supports jumping to an arbitrary page, but gets slower as the offset grows (the database still scans and discards skipped rows) and can show duplicate or missing items if data changes between page requests. Cursor-based pagination (?cursor=abc123&limit=20) resumes from a specific item using an indexed lookup, staying fast regardless of depth and stable under concurrent writes, at the cost of not being able to jump to an arbitrary page number. Cursor-based is the standard choice for large or frequently-changing collections; offset is fine for small, mostly-static ones.

Q: How does statelessness in REST relate to authentication? Doesn't the server need to remember who's logged in? Statelessness means the server keeps no session state between requests — but the client still authenticates on every single request, typically by sending a bearer token (like a JWT) in the Authorization header. The server verifies that token fresh each time rather than looking up a server-side session store, so any server instance can handle any request without needing shared session state — which is exactly what makes stateless APIs easy to scale horizontally behind a load balancer.

Q: What's the difference between 401 and 403, and why does it matter to get it right? 401 Unauthorized means the request has no valid authentication at all (missing or invalid token) — the server doesn't know who's asking. 403 Forbidden means the server does know who's asking, but that identity isn't permitted to do this. Getting this distinction right matters because clients (and monitoring/alerting systems) often react differently — a 401 might trigger a redirect to a login page, while a 403 should not, since re-authenticating wouldn't change the outcome.

Q: Why would an API use PATCH instead of PUT? PUT is meant to replace an entire resource with the representation given — omitted fields are conceptually being set to their default/absent state. PATCH is meant for partial updates — sending only the fields that changed, leaving everything else untouched. Using PUT for a partial update is a common bug source: a client that sends only a few fields to a strict PUT endpoint can unintentionally wipe out the fields it didn't include.

Q: What is HATEOAS, and how commonly is it actually implemented in real-world APIs? HATEOAS means a response includes links describing what actions are currently valid on that resource, so a client discovers what it can do next from the response itself rather than hardcoded, out-of-band knowledge. In practice it's genuinely rare — most APIs that call themselves "RESTful" stop at proper resource URLs and correct verb/status-code usage (level 2 on the Richardson Maturity Model) without adding hypermedia controls, because most clients are built against a specific, known API version anyway and don't benefit much from runtime link discovery.

Q: Why is token bucket generally preferred over a fixed-window counter for rate limiting an API? A fixed window resets sharply at its boundary, letting a client send close to double the intended rate by timing bursts around that edge. Token bucket refills continuously and allows a bounded burst up to the bucket's capacity while still enforcing a steady average rate over time, which matches how legitimate client traffic (a page load firing several requests at once) actually behaves far better than a strict, unforgiving fixed window does.

Q: What does an OpenAPI specification give you beyond a documentation page? It's a machine-readable contract that tooling can act on directly — generating client SDKs, generating server-side request validation, and driving automated contract tests that check a running API's real responses against what the spec promises. Treated only as documentation, with nothing enforcing it, an OpenAPI spec can silently drift from the actual implementation over time.

Q: Why is checking only the HTTP status code an incomplete way to test a REST endpoint? A status code alone says nothing about the response body's actual shape — a field could be missing, renamed, or the wrong type, and a status-only assertion would still pass. A thorough test validates the response against a schema (ideally the one published in the API's own OpenAPI spec), which catches structural regressions a status-code check alone would miss entirely.