API Design

🔴 P0 — the craft of designing APIs; shows engineering judgement, not just pattern knowledge

API design in system design interviews is about demonstrating engineering judgement, not perfection. Choose the right protocol (see Protocol Choices), model resources sensibly, and move on. Over-investing here is a bigger failure mode than under-investing.

• INTERVIEW: Prioritise balance. Show reasonable endpoints, don’t get stuck on details when there are architectural challenges to address. 4-5 key endpoints is sufficient.
• PITFALL: Over-investing interview time on API design. Junior and frontend roles may focus more here; senior and staff should spend time on the distributed systems aspects.
• INTERVIEW: Default to REST for the client-facing API, mention gRPC for inter-service communication only when it becomes relevant.

REST Conventions #

REST maps HTTP verbs to CRUD operations on resources. The mental model is resources and state, not actions.

Resource Modelling #

• CONVENTION: Resources are plural nouns: /tickets/ not /ticket/.
• PITFALL: Think in terms of resources, not operations. /updateUser and /startGame are anti-patterns. Use PUT /users/{id} and PATCH /games/{id} { "status": "started" }.
• CONVENTION: Path params vs query params: consider whether a value is required or optional:
  • Required → path param: /events/{id}/tickets (structural, identifies the resource)
  • Optional → query param: /tickets?event_id=123&section=VIP (modifier, filters results)

HTTP Methods and Idempotency #

• INSIGHT: POST is the dangerous one for retries because it’s neither safe nor idempotent. This is precisely why Idempotency Keys exist — to make non-idempotent operations safe to retry. See also Idempotency Keys (Implementation).

Passing Data #

Response Structure #

• RULE OF THUMB: Differentiate client errors (4XX) from server errors (5XX). Common codes: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 429 (Too Many Requests), 500 (Internal Server Error).

GraphQL #

Solves the over-fetching / under-fetching problem by letting clients declaratively specify the fields they need.

• INTERVIEW: Rarely needed in system design interviews because the scope is typically clear and not shifting. Only consider if the problem specifically involves flexible client-side data fetching for multiple client types.
• CHALLENGE: Introduces complexity: query parsing, schema validation, N+1 query problems (use dataloaders), per-field authorisation, and sophisticated caching strategies.
• MYTAKE: GraphQL feels like an inversion of control: the caller dictates the response shape. Powerful for product iteration velocity, expensive for backend complexity.

gRPC #

Binary protocol (protobuf) over HTTP/2 — significantly faster than JSON-over-REST for inter-service communication.

• INTERVIEW: For the API step of the delivery framework, show client-facing REST endpoints first. Mention gRPC for internal APIs only at the high-level design stage, and only with a quick callout:

I’ll use REST for the public API and gRPC for inter-service communication where we need performance and type safety.

• PITFALL: Don’t early-optimise by reaching for gRPC from the start. It’s only necessary when latency is dominated by network and serialisation costs rather than application logic.
• TRICK: For interviews, use REST-client syntax to quickly sketch endpoints. It’s faster to draw and easier for the interviewer to parse.

Pagination #

Large result sets must be paginated. Two approaches:

• INTERVIEW: Offset-based is fine for most interviews. Use cursor-based when the data is high-volume, real-time, and frequently appended — e.g. a social media feed.

Security Basics #

Focus on demonstrating awareness, not depth. These are touch-and-go topics in system design interviews.

Authentication & Authorisation #

• INSIGHT: JWT is powerful for distributed systems because any service with the verification key can validate independently. Pair with API gateway verification for a single auth checkpoint.
• INTERVIEW: Callout auth endpoints, mention JWT with server-side session storage, and move on.

Rate Limiting #

• Per-user, per-IP, or per-endpoint limits. Implemented at the API gateway layer. Returns 429 on violation.
• INTERVIEW: Mention for production-concern awareness, then carry on:

We’ll implement rate-limiting at the API gateway to prevent abuse.

• See Rate Limiting & Backpressure for the pattern-level treatment.

API Versioning #

See API Versioning Strategies for the full treatment. Quick summary:

• INTERVIEW: Default to URL versioning (/v1/users) for simplicity. Mention it off-hand when vocalising, don’t dwell on it.
• FLEX: Stripe uses dated API versions (2023-10-16) with additive-only changes — an elegant approach that avoids version proliferation. See Stripe Engineering: API Versioning.

References #

• HelloInterview: API Design

DDIA 2e Reference #

• Chapter 4: Encoding and Evolution (serialisation formats, schema evolution)
• Chapter 4: Dataflow Through Services (REST, RPC, message-passing)