jdfive

Interview Questions

This chapter collects the API design questions interviewers ask most often after you propose REST, gRPC, or GraphQL. Read each question, answer out loud, then compare with the model answer. Short, precise answers beat long ones.

For the breadth view in system design rounds, see API Design in System Design. For transport fundamentals, see Networking overview.

Q1. What does REST stand for, and what is it really?

REST means Representational State Transfer. It is an architectural style: clients manipulate representations of resources through a uniform interface, with stateless servers and cacheable responses where appropriate. HTTP is the common carrier; JSON is one representation format — not the definition of REST.

See REST Constraints for the full constraint list.

Q2. What is a resource vs a representation?

A resource is the abstraction (an order, a user). A representation is the concrete bytes (JSON, XML) exchanged over the wire. Clients never “get the resource itself” — they get a representation they can cache, validate, and send back on update.

See Resources & URIs.

Q3. What is idempotency and why does it matter?

Idempotent means repeating the same request does not compound unintended side effects. GET, PUT, DELETE are idempotent in HTTP semantics (assuming your server implements them that way). POST is not — use Idempotency-Key for payments and creates so retries after timeouts do not double-charge.

See Methods & Idempotency and Versioning, Pagination & Idempotency.

Q4. What does stateless mean in REST?

The server must not require server-side session memory to interpret a request. Credentials and context travel in the message (headers, URI, body). Resource data in databases is fine; hidden sticky session RAM required for correctness is not.

See Statelessness.

Q5. 401 vs 403?

401 Unauthorized — not authenticated. Missing or invalid token; client should log in or refresh.

403 Forbidden — authenticated but not permitted for this action or resource.

Swapping these is a common production bug interviewers watch for.

See Status Codes & Errors.

Q6. When do you use 409 Conflict?

When the request conflicts with current server state: duplicate unique key, optimistic locking version mismatch, illegal state machine transition (ship a cancelled order). Prefer 409 over generic 400 when the client could retry or refresh state differently.

Q7. What is Problem Details (RFC 7807)?

A standard error document with MIME type application/problem+json. Fields include type (URI identifying error class), title, status, detail, instance (correlation id). Lets clients and gateways handle errors uniformly.

Q8. Offset vs cursor pagination?

Offset — simple (?page=2&limit=20), maps to SQL OFFSET, but slow at large offsets and unstable if rows shift between pages.

Cursor — opaque token encoding position in a stable sort (e.g. created_at, id); better for feeds and large tables under concurrent writes.

See Versioning, Pagination & Idempotency.

Q9. Where should API version live?

Both are common: URL prefix (/v1/orders) and Accept header vendor media type (application/vnd.example.v2+json). Pick one org standard; never break clients silently — version bump or deprecation window.

Q10. Is GraphQL REST?

No. GraphQL is a different style: typically one endpoint, client-specified field tree, schema contract. It runs over HTTP but does not model many resource URLs with HTTP verb semantics the REST way.

See GraphQL.

Q11. What is the GraphQL N+1 problem?

Resolvers that load a parent, then run one query per child, cause N+1 database round trips. Fix with batching (DataLoader), SQL joins, or query lookahead to prefetch relationships.

Q12. When would you choose gRPC over REST?

Internal services needing strong proto contracts, binary efficiency, streaming, and generated clients. Not when you need broad HTTP/CDN caching of public reads or direct browser consumption without gRPC-Web or a BFF.

See gRPC and REST vs RPC vs GraphQL.

Q13. Name three REST misconceptions interviewers expect you to debunk

  1. “REST = JSON” — JSON is a representation; REST is constraints. XML can be RESTful too.
  2. “Always POST” — loses caching, clear semantics, intermediary visibility.
  3. “REST cannot search” — use query params on GET for filters; use POST for heavy search bodies when justified.

Also worth stating if time allows: GraphQL does not replace REST everywhere (resolver and caching cost); returning 200 with { "error": true } breaks monitors and caches — use proper 4xx/5xx.

Q14. Whiteboard prompt: “Design REST API for orders”

A strong outline in five minutes:

  1. Resources — /orders, /orders/{id}, optionally /customers/{id}/orders
  2. Methods — GET list/detail, POST create, PATCH status, DELETE cancel policy
  3. Status codes — 201 + Location, 404, 409 on duplicate/idempotency conflict, 422 validation
  4. Lists — cursor pagination, filter by status, sort by -created_at
  5. Creates — Idempotency-Key on POST if orders trigger payment
  6. Errors — Problem Details shape
  7. Version — /v1/ prefix stated once

Adjust depth to time box. Do not jump to Kafka unless the prompt scales beyond API design.

Course complete

You covered REST as constraints, not JSON; resources and HTTP semantics; status codes and Problem Details; versioning, pagination, and idempotency keys; and when gRPC or GraphQL earns its complexity.

Continue learning: