API Design Interview Guide

Every question uses the same frame: what it tests, progressively stronger answers, green flags, red flags, follow-up and a practical scenario. Strong candidates reason from consumers, guarantees and evolution — not endpoint conventions.

The Retried Paymentintermediate

A client sends a payment request, times out, and retries. How should the API behave?

Tests: Whether the candidate sees that a timeout is ambiguous, not a failure · Idempotency-key mechanics: storage, replay, scope · Concurrency: what happens when the retry arrives while the original is still running
Offset or Cursor?intermediate

You're adding pagination to a list endpoint. Offset or cursor pagination — how do you decide?

Tests: Whether the candidate asks about the access pattern before picking a mechanism · Understanding of what concurrent writes do to offset pages · Awareness of the database cost behind each promise
When Is v2 Actually Needed?advanced

When does an API need a new version — and when doesn't it?

Tests: Whether the candidate can separate breaking from additive change · Understanding of what a version number actually promises consumers · Awareness of the cost of running multiple versions
REST or gRPC for This Service?intermediate

A team is building a new service API and asks: REST or gRPC? What do you ask them before answering?

Tests: Whether the candidate interrogates the consumer environment before choosing a style · Concrete knowledge of what each style buys and costs · Awareness of browser and tooling constraints
Design the Error Responsebeginner

Design the error response for a payments API. What does a client need to see when a request fails?

Tests: Whether errors are treated as contract, not afterthought · Machine-readable vs human-readable separation · Support and debugging workflow awareness
PUT vs PATCHbeginner

What's the difference between PUT and PATCH, and when does the choice actually matter?

Tests: Replace vs partial-modify semantics · Idempotency of each method · The null-vs-absent trap in partial updates
403 or 404?beginner

A user requests a resource that exists but they may not access it — 403 or 404? Why might you choose either?

Tests: Understanding that status codes leak information · Consistency as a contract property · Judgment over rule-following
Two Clients, One Resourceadvanced

Two clients load the same resource, both edit it, and both save. Design the API so the second save doesn't silently destroy the first.

Tests: Recognition of the lost-update pattern · Version/ETag mechanics with If-Match and 409/412 · Who resolves the conflict, and how
The 15-Minute Reportintermediate

Generating a report takes 15 minutes. How do you design the API for it?

Tests: Recognizing when request/response stops fitting · The async job pattern: 202, job resource, states · How completion reaches the client
Design Webhook Deliveryadvanced

Design webhook delivery for a payments platform. What must the contract cover for consumers to build something reliable?

Tests: At-least-once delivery and its consequences · Retry schedule, ordering, and dead-lettering · The security contract: signatures, timestamps, replay
What Does a 429 Promise?intermediate

Your API rate-limits clients. What should a 429 response contain, and what should the rate-limit contract promise?

Tests: Rate limiting as documented contract behavior, not just protection · Retry-After and limit-header mechanics · Scope: what the limit is keyed on
The Real Price of GraphQLadvanced

A team wants to adopt GraphQL to “fix over-fetching and the N+1 calls from mobile”. What does GraphQL actually buy, and what does it cost?

Tests: Whether the candidate knows where N+1 goes rather than believing it disappears · Server-side costs: resolvers, authorization, caching, query cost control · Fit assessment: consumer diversity as the real justification
Batch of 5, 2 Failadvanced

A client submits a batch of 5 operations and 2 fail. What should the API do — and what must the contract have said beforehand?

Tests: Atomic vs independent batch semantics as an explicit contract choice · Per-item result reporting design · Retry interaction: what does the client resend?
Renaming status to stateintermediate

Is renaming response field `status` to `state` a breaking change? How would you actually do it?

Tests: Recognizing a rename as remove + add · The additive migration sequence · Telemetry-driven removal decisions
API Keys or OAuth?intermediate

When is an API key enough, and when do you need delegated authorization like OAuth?

Tests: Whose resources are being accessed — the caller's or a third user's · Key lifecycle: scoping, rotation, revocation · Understanding what OAuth actually adds beyond “more secure”
When Does a BFF Earn Its Keep?advanced

When does a backend-for-frontend earn its complexity — and when is it just another service to keep alive?

Tests: The concrete problems a BFF solves (fan-out, payload shaping, client divergence) · Honest accounting of its costs: ownership, duplication, another hop · Alternatives that are cheaper for the same symptom

Universal signals

Green flags →

Begins with consumers, plans retries and idempotency, bounds every list, designs stable errors, thinks in compatibility horizons.

Red flags →

REST-means-CRUD, 200-with-error=true, frontend-enforced authorization, version everything, never version anything.