What API design interviews actually test (and why reading Q&A isn’t enough)
API design interviews evaluate how you translate product requirements into a stable, usable contract between clients and services. Interviewers look for: (1) requirements clarification (users, operations, constraints), (2) resource modeling (entities, relationships, invariants), (3) semantics (HTTP methods, status codes, idempotency), (4) consistency (naming, pagination, errors), (5) non-functional concerns (auth, rate limits, observability, versioning), and (6) evolution (backward compatibility and migration). Reading Q&A helps you recognize terms, but it won’t build the skill interviewers score: choosing a design under ambiguous constraints and defending it clearly. In real interviews, you must ask the right questions, converge on a coherent API quickly, and adapt when the interviewer changes requirements (e.g., “now it must be bulk,” “now it must be public,” “now it must support mobile offline”). Mock interviews are key because they force retrieval under time pressure, expose gaps in your mental model, and improve how you communicate tradeoffs and edge cases.
A live-interview framework to answer any API design question
1) Clarify the product and actors
Ask who uses the API (internal service, third-party devs, mobile clients), core user journeys, and success metrics. Confirm operations: create/read/update/delete, search/filter, bulk, async workflows, webhooks, and permissions.
2) Define resources and identifiers
Model nouns as resources (e.g., /users, /orders). Decide ID type and exposure (UUID vs numeric, opaque vs meaningful). Define relationships and nesting rules; avoid deep nesting and prefer linking where appropriate.
3) Specify endpoints and semantics
Map operations to HTTP methods, define request/response shapes, and state idempotency expectations. Use consistent naming, pluralization, and field conventions. Call out partial updates (PATCH) vs full replacement (PUT).
4) Handle pagination, filtering, sorting, and search
Pick a pagination strategy (cursor for large/real-time datasets, offset for simple/finite lists). Define filter and sort parameters, stable ordering, and response metadata (next_cursor, total when feasible).
5) Define errors, validation, and status codes
Standardize error format (machine code + human message + field errors + request_id). Choose status codes intentionally (400 vs 422, 401 vs 403, 409 for conflicts, 429 for rate limits). Discuss retries and idempotency keys for safe replays.
6) Address authN/authZ, rate limits, and abuse
Decide auth mechanism (OAuth2/JWT/mTLS/API keys) and permission model (scopes, roles, resource-level ACL). Specify rate limit headers, quotas, and how clients should back off.
7) Plan for evolution: versioning and compatibility
Prefer backward-compatible additive changes. When breaking is unavoidable, define versioning strategy (URI, header, media type), deprecation policy, and migration plan. Mention contract testing and API docs as enforcement.
8) Validate with examples and edge cases out loud
Walk through 2–3 concrete requests/responses, including failure cases and concurrency (duplicate creates, stale updates). Invite the interviewer to challenge assumptions and adapt cleanly.
Common high-signal mistakes interviewers notice
- •Jumping into endpoints without clarifying requirements (public vs internal, scale, async needs, permission model).
- •Using RPC-style paths (/doThing) everywhere without a reason, leading to inconsistent semantics and poor evolvability.
- •Misusing HTTP methods (e.g., GET that changes state) and ignoring idempotency for retries and duplicate requests.
- •No story for pagination at scale (offset only) or no stable ordering, causing missing/duplicate items across pages.
- •Inconsistent naming and payload conventions across endpoints (singular/plural, snake/camel case, timestamps, enums).
- •Treating errors as an afterthought: vague 400s, no machine-readable codes, no field-level validation, no request_id.
- •Confusing authentication (who are you?) with authorization (what can you do?), and skipping scope/role modeling.
- •No concurrency or conflict handling (lost updates, duplicate creates, 409 vs 412, ETags/If-Match).
- •Breaking changes without a versioning/deprecation plan, or versioning everything prematurely without compatibility strategy.
- •Not verifying the design with concrete request/response examples and edge cases under time pressure.
Realistic interview scenario: Design an API for creating and managing subscriptions
Weak Answer
Q: Design an API for subscriptions. A: We’ll have endpoints like /createSubscription, /cancelSubscription, /getSubscription. Use POST for create, GET for get. Return 200 for success. Add authentication. That’s it.
Strong Answer
Q: Design an API for subscriptions. A: Clarifying: Are clients internal or third-party? Do we need trials, pausing, plan changes, proration, webhooks? Assume a public API for merchants to manage customer subscriptions and we need create, view, update plan, cancel, and list. Resources: - /customers/{customer_id} - /subscriptions/{subscription_id} - /plans/{plan_id} Key endpoints: - POST /subscriptions (idempotent with Idempotency-Key) - body: {customer_id, plan_id, payment_method_id, trial_end?, metadata?} - 201 + subscription representation - GET /subscriptions/{id} - GET /customers/{customer_id}/subscriptions?status=active&limit=50&cursor=... - cursor pagination, stable sort by created_at - PATCH /subscriptions/{id} - allow {plan_id, pause_behavior, metadata} - use If-Match with ETag for optimistic concurrency - POST /subscriptions/{id}/cancel - body: {effective_at: "period_end"|"immediate"} - returns 202 if asynchronous cancellation requires downstream confirmation Errors: - 401 if missing/invalid token, 403 if token lacks scope subscriptions:write - 409 if subscription already canceled or plan change conflicts with current state - 422 for field validation (e.g., trial_end in the past) Non-functional: - Rate limit: 429 with Retry-After - Webhooks: subscription.updated, subscription.canceled with signed payloads Evolution: - Add fields additively; avoid breaking renames; deprecate with sunset headers and a migration window.
Why it works
The good answer shows structured discovery, clear resource modeling, correct HTTP semantics (including idempotency and async handling), and operational concerns (auth scopes, rate limiting, webhooks, concurrency). It also demonstrates communication quality: the candidate narrates assumptions, validates with examples, and anticipates edge cases—exactly what interviewers need to trust the design.
How to turn API Q&A into a skill you can demonstrate
Use the questions below as a practice set, not a script. On CrackTheOffer, you can run mock API design interviews that simulate real pressure: ambiguous requirements, follow-up twists, and feedback on both design quality and communication. The goal is to practice the repeatable behaviors interviewers score—clarifying, structuring, deciding, and defending tradeoffs—until they’re automatic.