API design
REST API design: interview questions and practical design
REST API design is the discipline of exposing resources, representations, and state transitions through a contract that clients can evolve against.
Written and reviewed by Sahil Srivastav
What it actually is
REST API design is the discipline of exposing resources, representations, and state transitions through a contract that clients can evolve against.
A vague API makes every client guess about validation, retries, pagination, and errors. Those guesses diverge and become compatibility bugs.
The useful interview answer is precise about the boundary: Use nouns for resources and reserve action endpoints for operations that are not naturally resource state. `POST /payments` creates an intent; `PATCH /payments/:id` changes a representation under an explicit rule.
Why it matters in production
A vague API makes every client guess about validation, retries, pagination, and errors. Those guesses diverge and become compatibility bugs.
Good resource boundaries make caching, authorisation, and observability easier because each operation has a clear identity and effect.
How it works
Resource and command boundary
Use nouns for resources and reserve action endpoints for operations that are not naturally resource state. `POST /payments` creates an intent; `PATCH /payments/:id` changes a representation under an explicit rule.
Representation and compatibility
The wire shape is a contract. Add fields compatibly, tolerate unknown response fields, and distinguish omitted, null, and empty values when they have different meaning.
Safe retries
Define method safety and idempotency from the actual handler, not its verb. A POST may be made idempotent with a key; a PUT is safe to retry only when it replaces the same state.
Implementing it
Write the resource model and invariants before choosing controller names.
Specify status codes, validation errors, pagination, and retry behaviour for one complete workflow.
Test a client retry and an old client reading a response after a new field is added.
Interview questions and how to answer them
What makes an API RESTful enough for an interview?
Explain resource identity, representations, uniform methods, cache or conditional semantics where relevant, and a stable error contract. Do not turn the answer into a checklist of URL shapes.
When is an action endpoint reasonable?
When the operation has no useful resource representation or is a domain command such as cancelling a payment. State its idempotency and resulting state explicitly.
How do you evolve a REST API?
Add compatible fields and endpoints first, observe consumers, then deprecate with a published timeline. Avoid changing the meaning of an existing field silently.
Answers that lose the round
- Treating REST as a requirement to expose database tables directly.
- Returning 200 for every outcome, leaving clients unable to distinguish conflict from success.
- Changing field meaning while preserving the same name.
- Using an action endpoint to hide an unclear state machine.
FAQ
Should every endpoint be CRUD?
No. Model ordinary resource changes with standard methods, but use a command when the domain operation has a distinct invariant or lifecycle.
Where should validation live?
Transport validation rejects malformed input; domain validation enforces business invariants so non-HTTP callers receive the same protection.
How should I discuss REST versus RPC?
Compare the contract and evolution needs of the system. Resource-oriented APIs are useful when representations and standard semantics matter; commands can be clearer for workflows.