API Design for System Design Interviews
How to design APIs in system design interviews: resources, idempotency, pagination, errors, versioning, async workflows, and contracts.
APIs reveal your product model
In system design interviews, APIs are not filler before the architecture diagram. They reveal what resources exist, who owns them, which actions are synchronous, and which operations need idempotency or permissions.
A good API section should be small but precise: the core endpoints, request shape, response shape, error semantics, and the identifiers that flow through the system.
Name the hard contract details
Most weak API answers list endpoints and stop. Stronger answers call out the details that break real systems: pagination, dedupe keys, optimistic concurrency, partial failure, validation, retry safety, and versioning.
- POST operations that clients retry need idempotency keys.
- List endpoints need cursor pagination when ordering changes under writes.
- Errors should be semantic, not just HTTP status codes.
- Long-running work should return a job ID or event-driven callback contract.
Choose sync or async intentionally
Not every API should finish the work before returning. Upload processing, webhook delivery, notification fan-out, video transcoding, and model inference queues often need an asynchronous contract.
Say what the client receives immediately, how it checks status, how retries behave, and how duplicate requests are handled. That is the level of contract thinking interviewers notice.