API Design Interview Questions — every contract is a reef

An API is the contract your service shows the outside world — the endpoints, shapes, and rules. API design interviews test whether you can name the resource, handle retries, and survive a partner engineer six months later. Drawing endpoints is the easy part.

API design is the round where smart candidates fall apart the fastest. Not because they don't know REST. Because they start drawing endpoints before they name the resource, and by round three they hand-wave the retry story because they never had one.

The good news: API rounds repeat. Strip away the domain ("design a payments API," "design a task API," "design a translation API") and there are five families of questions. Learn those five, and the round becomes legible.

What the interviewer is actually listening for

The strong API design answer isn't the clever one. It's the one that names the trade-off early. The candidates who move the needle prove five things:

1. They named the resource and its lifecycle before naming endpoints.
2. They separated synchronous requests from async workflows.
3. They protected correctness under retries, duplicates, and partial failure.
4. They chose pagination, filtering, and status codes deliberately.
5. They explained the contract like the engineer who would maintain it.

That last one is the tell. Interviewers aren't looking for "the one true REST shape." The common failure mode: the candidate has every HTTP verb memorized but can't explain what happens when the client retries a POST. That's the signal the answer is toy-sized.

Diagram

Copy source

Rendering diagram...

The five API design question families that keep repeating

1. Resource plus CRUD questions

This is the baseline family:

• design a task API
• design an orders API
• design a translation API
• design a comments API

The first move is not POST versus PUT. The first move is naming the resource and its lifecycle. Google's own API design guide (AIP-121: Resource-oriented design) puts this first for a reason — resources are the stable primitives; verbs come after.

I always ask candidates four questions before they draw a single endpoint:

• What is the main resource?
• What fields are client-controlled vs server-controlled?
• Is create/update/delete actually required?
• Is this object long-lived, append-only, or state-machine driven?

A calm opening sounds like:

• "The resource is translation_job, not translate."
• "Creation is asynchronous because translation may call external providers."
• "The server owns id, status, and timestamps."

That sounds much sharper than POST /doTranslation. The verb-first endpoint is the fastest tell that a candidate skipped domain modeling. Google AIP-122: Resource names is the reference if you want to pressure-test your URI shape during prep.

2. List endpoints with filtering, sorting, and pagination

This is where otherwise solid answers get sloppy. Senior candidates ace resource modeling and then say "we'll paginate later" as if the browse path isn't half the contract.

Common versions:

• list transactions for an account
• list messages in a conversation
• browse orders for a merchant
• fetch translation jobs created by a user

In production, cursor pagination beats offset pagination at scale — Milan Jovanovic's deep dive benchmarks a 17x slowdown on deep offset pages, and Contentful moved their entire API off offset for the same reason. For interview purposes, cursor pagination is the default when the list is large or frequently updated (Source: Speakeasy — Pagination Best Practices).

HTTP

Copy

GET /v1/translation-jobs?status=completed&limit=20&cursor=job_018

JSON

Copy

{ "items": [ { "id": "job_021", "sourceLanguage": "en", "targetLanguage": "es", "status": "completed", "createdAt": "2026-04-09T13:02:00Z" } ], "nextCursor": "job_021" }

The sentence that lands in the room:

"I want pagination tied to a stable ordering so inserts between pages don't cause duplicates or skipped records."

That answer tells me you've actually paginated through a list that was being written to. The cursor should also be opaque — base64-encoded or encrypted — so clients can't hard-code values and you can evolve the pagination logic later without breaking them.

3. Async workflows, webhooks, and eventual completion

Many real API design prompts are workflow problems, not request/response problems. The candidate who treats them as single-round-trip ones always loses points.

Common versions:

• payment or transfer processing
• file upload and processing
• webhook delivery
• third-party sync jobs
• translation or moderation jobs

Stop pretending the response is immediate.

HTTP

Copy

POST /v1/translation-jobs Idempotency-Key: req_8f2a Content-Type: application/json { "text": "Ship the patch first, then optimize it.", "sourceLanguage": "en", "targetLanguage": "fr" }

JSON

Copy

{ "id": "job_021", "status": "queued", "pollUrl": "/v1/translation-jobs/job_021" }

The talk-track that works in the interview:

• "Create returns quickly with a job resource."
• "Clients can poll, or we can push completion with webhooks."
• "Webhook delivery assumes retries and out-of-order arrival."

That last line matters more than most candidates realize. Both Stripe and Twilio explicitly document at-least-once delivery — Stripe retries failed webhooks with exponential backoff for up to 3 days, Twilio retries for up to 4 hours. The industry standard, as Hookdeck's guide puts it, is at-least-once delivery paired with idempotent consumers. Together they produce effective exactly-once processing. If your answer assumes exactly-once delivery, you've already diverged from every webhook contract you're likely to integrate with in production.

If the prompt contains "integration," "provider callback," or "background processing" — talk about async boundaries early.

4. Idempotency, retries, and rate limiting

This is the production-quality layer that separates clean answers from toy answers. It's also the answer Plaid specifically asks about — Plaid's interview loop includes an explicit rate-limiter API design question.

Interviewers love asking what happens when:

• the client times out and retries
• the same request arrives twice
• a partner system sends duplicate webhook events
• one customer sends traffic spikes far above everyone else

The recurring tools:

• idempotency keys for unsafe writes
• event IDs for webhook dedupe
• per-user or per-token rate limits
• clear retry semantics and error responses

The canonical reference here is Stripe's engineering post on idempotency — if you read one thing before an API design round, read that. Stripe stores the result (status code and response body) of the first request keyed by Idempotency-Key, and every subsequent request with the same key returns the same logical outcome (Source: Stripe docs — Idempotent requests). Brandur Leach, a former Stripe engineer, walks through the actual Postgres implementation including the transaction boundaries and concurrent-request edge cases — that's the level of depth that lands at senior+.

A compact example:

• POST /payments accepts Idempotency-Key
• the server stores the key plus the resulting payment ID
• repeated requests with the same key return the same outcome, even on a 500

The sentence production-minded interviewers remember:

"I don't want a network retry to create two charges, so I'd make create idempotent at the contract boundary."

Adding idempotency as an afterthought at the end is a miss. The stronger move is to name it as part of the original design, before the interviewer has to ask.

5. Auth, versioning, and error contracts

This family is less flashy, but it's where maintainability lives. The candidates who nail it are the ones who've actually maintained an API for more than six months.

Common follow-ups:

• how do clients authenticate?
• how do you evolve the contract?
• what does an error response look like?
• what happens when a user can see a resource but not mutate it?

You don't need a whole identity platform. You need a clear answer.

For most interview prompts:

• use bearer-token auth unless the prompt needs deeper identity discussion
• keep versioning simple, usually path-based like /v1/...
• make errors structured and machine-readable

Example:

JSON

Copy

{ "error": { "code": "rate_limit_exceeded", "message": "Retry after 30 seconds." } }

The win is consistency. If your success responses are careful but your error shape is vague, the contract feels unfinished. That's a tell — the candidate thought about the happy path and stopped (Source: Hello Interview — API Design for System Design).

Common mistakes that cost easy points

Starting with verbs instead of resources

/createOrder and /sendWebhookNow signal you skipped the domain model. Name the resource first, then the operation. Google's AIP-121 exists for exactly this reason — resources are stable, verbs drift.

Hand-waving pagination

If you say "we'll paginate later," the interviewer learns you haven't really designed the browse path. The common failure: the candidate aces resource modeling and then loses the round because their list endpoint can't survive concurrent writes.

Forgetting retries and duplicates

This is the fastest way to make a practical answer feel toy-sized. Production systems retry. Partners retry. Browsers retry. Your contract needs a story about what happens on the second attempt.

Making every workflow synchronous

If the work takes time, say so. Returning 202 Accepted with a job resource is almost always cleaner than faking an immediate result. The interviewer who's watched real translation or moderation workflows knows the synchronous framing is the tell.

Ignoring developer experience

Twilio- and Plaid-style API questions reward contract clarity as much as raw correctness. Predictable names, consistent shapes, explicit docs. In production, this is the moment where partner engineers either trust your API or build a wrapper around it to paper over inconsistencies.

A better 2-hour prep plan

If you only have one real prep block before an API round, do this:

1. 25 minutes: model 3 resources and sketch CRUD plus state transitions
2. 25 minutes: design one list endpoint with filtering, sorting, and cursor pagination
3. 25 minutes: design one async workflow with polling plus webhook completion
4. 20 minutes: talk through idempotency, retries, and rate limits for that workflow
5. 25 minutes: practice explaining status codes, auth, and error shapes out loud

That's enough to make the round feel familiar.

If you want the AI-tooling version of the same pressure, read AI-Assisted Coding Interviews.

The pattern to remember:

• resource
• contract
• async boundary
• protection against retries
• clear explanation

That's the real API design interview loop. Every candidate who moves through all five in the first 15 minutes gets a strong recommendation from me before the round is over.