API Design Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps

API design interviews in 2026 are less about memorizing REST conventions and more about showing that you can turn a messy product requirement into a stable contract other teams can safely build on. The strongest candidates clarify the use case, define resources and workflows, reason about latency and consistency, then explain how the API will evolve without breaking clients. This API Design interview cheatsheet in 2026 gives you the patterns, examples, practice plan, and common traps you need to sound practical instead of academic.

API Design interview cheatsheet in 2026: the 30-second frame

When the interviewer says “design an API for X,” do not jump straight to endpoints. Use this frame:

1. Client and user: who calls the API, how often, and from where?
2. Core workflow: what job must the API complete end to end?
3. Resource model: what nouns are stable enough to expose?
4. Operations: what can clients create, read, update, delete, search, or subscribe to?
5. Non-functional needs: latency, scale, reliability, privacy, auditability, compliance.
6. Contract details: request/response schema, errors, idempotency, pagination, versioning.
7. Evolution plan: how the API changes safely over time.

A good opening sounds like: “Before endpoints, I want to pin down the primary client. Is this public third-party API, internal service API, or first-party mobile/web API? That choice affects auth, rate limits, error detail, and backward compatibility.” That sentence immediately signals maturity.

Where API design shows up in interviews and jobs

API design appears in backend, platform, full-stack, staff engineer, solutions engineering, developer experience, infra, data platform, and engineering manager loops. It may be framed as a system design problem (“design a payments API”), a product problem (“design the public API for scheduling appointments”), or a debugging conversation (“why did this API become hard to maintain?”).

In real jobs, API design is where product sense meets distributed systems. A weak API turns every future feature into custom client logic. A strong API makes the common path obvious, the dangerous path hard, and the migration path explicit.

Interviewers are usually testing five things:

• Can you clarify ambiguous requirements without stalling?
• Can you design a stable domain model instead of endpoint soup?
• Can you handle edge cases like retries, duplicates, partial failure, and authorization?
• Can you explain tradeoffs in REST, GraphQL, gRPC, async events, and webhooks?
• Can you make the API operable: logs, metrics, rate limits, docs, and deprecation policy?

The API design interview workflow

Use this sequence for almost any prompt.

1. Clarify the API type

Ask whether the API is public, partner-facing, internal, or first-party. Public APIs optimize for stability, documentation, compatibility, predictable errors, and abuse protection. Internal APIs can move faster, but still need clear ownership and observability. First-party APIs can lean on shared auth and release coordination, but mobile clients still create backward compatibility pressure because old app versions stay in the wild.

2. Define the main use cases

List the two or three workflows the API must support. For a ticketing API, that might be search events, reserve seats, pay, issue tickets, refund. For a messaging API: create conversation, post message, list messages, mark read, receive notification. Avoid designing every possible endpoint. Interviewers reward focus.

3. Model resources and state transitions

Resources are nouns; state transitions are verbs with business meaning. A payment may move from requires_confirmation to processing to succeeded or failed. A booking may be held, confirmed, cancelled, or expired. State modeling is where you show product and correctness thinking.

4. Choose protocol style

REST is the default for public CRUD-ish APIs. GraphQL is useful when clients need flexible reads over a graph and you can absorb the operational complexity. gRPC fits internal low-latency service-to-service APIs with typed contracts. Async events and webhooks fit long-running workflows and third-party notifications. A senior answer can mix them: REST for commands, events/webhooks for asynchronous state changes, gRPC internally.

5. Specify contract details

Give concrete request and response examples. Define error format. Explain idempotency, pagination, filtering, sorting, partial updates, and rate limits. You do not need every field, but you need enough detail that another engineer could implement against it.

6. Cover operations and evolution

Mention API docs, OpenAPI/protobuf schemas, SDK generation, contract tests, backward-compatible changes, versioning, deprecation windows, dashboards, logs, and alerting. This is where many candidates stop too early.

Example: design a payments API

A strong answer starts with constraints: “I’ll assume this is a public API for merchants, payments can be card or bank debit, and the main workflow is authorize, capture, refund, and receive async confirmation.” Then propose resources.

| Resource | Purpose | Key fields | |---|---|---| | Customer | Optional stored buyer profile | id, email, metadata | | PaymentMethod | Tokenized card/bank/wallet | id, type, billing_details | | PaymentIntent | A requested payment and its state | amount, currency, status, capture_method | | Charge | Attempt against a payment method | status, failure_code, network_reference | | Refund | Money returned for a charge | amount, reason, status |

Example endpoints:

POST /v1/payment_intents
GET /v1/payment_intents/{id}
POST /v1/payment_intents/{id}/confirm
POST /v1/payment_intents/{id}/capture
POST /v1/charges/{id}/refunds
GET /v1/refunds/{id}

Use Idempotency-Key on all write operations. If a merchant retries POST /payment_intents after a timeout, the server should return the original result rather than creating a duplicate payment. Explain that the idempotency key is scoped to merchant account plus endpoint plus request body hash, retained for perhaps 24 hours to 7 days depending on risk.

For async state, expose webhooks:

payment_intent.succeeded
payment_intent.payment_failed
refund.succeeded
refund.failed

A practical webhook design includes signing secrets, delivery retries with exponential backoff, event IDs for dedupe, an event retrieval endpoint, and a dashboard for failed deliveries. This is the difference between “I know endpoints” and “I have seen APIs run in production.”

REST patterns that still matter

REST is not dead. It remains the easiest design language for most interviews. Use these patterns:

• Plural resource names: /users, /orders, /projects/{project_id}/tasks.
• HTTP verbs with predictable meaning: GET safe, POST create/command, PATCH partial update, DELETE remove or cancel.
• Nested resources only when ownership is real: /accounts/{account_id}/users is fine; avoid five-level paths.
• Command endpoints for business actions: /bookings/{id}/cancel is clearer than overloading PATCH with magic status changes.
• Consistent envelope or no envelope: choose one. Public APIs often use envelopes for metadata; internal APIs may return raw objects.
• Stable IDs: opaque IDs like pay_123, not database integers.
• Pagination: cursor-based for changing lists, offset only for small stable admin tables.

Cursor pagination example:

{
  "data": [{"id": "msg_1"}],
  "next_cursor": "eyJsYXN0X2lkIjoibXNnXzEifQ",
  "has_more": true
}

Explain why cursor pagination handles inserts/deletes better than offset pagination. If a feed receives new messages while a client pages, offset pagination can skip or duplicate rows.

GraphQL, gRPC, and events: when to choose each

Use GraphQL when clients need flexible shape, the domain is graph-like, and you can invest in schema governance, caching strategy, query cost limits, and resolver performance. Say it is strong for multi-platform product surfaces, weaker for write-heavy workflows or third-party APIs that need simple audit logs.

gRPC is strong for internal service calls because protobuf gives strict typing, streaming is first-class, and generated clients reduce drift. Mention deadlines, retries, backpressure, and compatibility rules for protobuf fields. Do not choose gRPC for public browser-based APIs unless there is a clear reason.

Events are not a replacement for APIs. They complement APIs when something happens after the original request returns. Good events are immutable facts, not commands disguised as facts. invoice.paid is an event; sendEmailNow is a command.

Error design and status codes

Bad candidates say “return 400 or 500.” Strong candidates design errors clients can recover from.

| Case | Status | Retry? | Example code | |---|---:|---|---| | Missing required field | 400 | No | invalid_request | | Bad credentials | 401 | After token refresh | unauthenticated | | Authenticated but not allowed | 403 | No | permission_denied | | Resource not found | 404 | Maybe if eventual consistency | not_found | | Duplicate conflict | 409 | Maybe after fetch | conflict | | Rate limited | 429 | Yes after reset | rate_limited | | Internal failure | 500 | Yes with backoff | internal_error | | Dependency unavailable | 503 | Yes with backoff | service_unavailable |

Error body:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key.",
    "request_id": "req_abc123",
    "retry_after_seconds": 30
  }
}

Keep messages useful but not leaky. Do not expose stack traces, internal hostnames, or sensitive authorization detail.

Auth, authorization, and tenant boundaries

For public APIs, talk about API keys, OAuth 2.0, scoped tokens, key rotation, secret storage, and audit logs. For internal APIs, mention service identity, mTLS, workload identity, and least-privilege access. For multi-tenant systems, every query must be tenant-scoped at the authorization layer, not just the controller layer.

A great interview line: “I would make tenant ID derivable from the authenticated principal, not trusted from the request body.” That one sentence catches a common security bug.

Also cover authorization granularity. It is not enough to authenticate a user. Can they read this account? Can they refund this payment? Can they export data? Administrative actions should have explicit permissions and audit trails.

Versioning and backward compatibility

Most API changes should be additive: add optional fields, add new enum values carefully, add endpoints, add webhook event types. Breaking changes include removing fields, changing semantics, making optional fields required, changing ID format, and reusing error codes for new meanings.

Versioning options:

• Path versioning: /v1/orders. Simple and common for public APIs.
• Header versioning: cleaner URLs, more tooling friction.
• Date-based versioning: useful when clients pin behavior by date.
• No major versions: possible internally with strict compatibility discipline.

Deprecation policy matters. Say: “For a public API, I would publish a migration guide, instrument usage of deprecated fields per API key, notify affected clients, and keep the old behavior for a defined window, often 6-18 months depending on enterprise contracts.”

Common traps that cost offers

• Starting with endpoints before requirements. You look junior even if the endpoints are okay.
• CRUD-only thinking. Real domains have workflows, state transitions, async processing, and failure modes.
• Ignoring idempotency. Any money, booking, inventory, or message-send API needs retry safety.
• Returning vague errors. Clients need machine-readable codes and request IDs.
• No pagination plan. Large lists without pagination are an instant red flag.
• Trusting client-supplied tenant IDs. This is a security smell.
• Overusing GraphQL. Do not pick it because it sounds modern. Explain operational tradeoffs.
• No observability. APIs need request IDs, logs, metrics, latency percentiles, error rates, and dashboards.
• No migration story. Mature API design includes safe evolution.

A 7-day API design practice plan

Day 1: Review REST fundamentals, HTTP semantics, status codes, pagination, filtering, sorting, and patch semantics. Redesign a simple todo API with better errors and pagination.

Day 2: Practice stateful workflows: payments, bookings, order fulfillment, returns, subscription billing. Draw state machines and identify idempotent operations.

Day 3: Practice auth and multi-tenancy. Design an API for a SaaS workspace with admins, members, guests, service accounts, and audit logs.

Day 4: Compare REST, GraphQL, gRPC, and events. For three prompts, explain which you would use and why.

Day 5: Write concrete schemas. For one prompt, produce request/response JSON, errors, webhooks, and versioning policy.

Day 6: Do a timed mock. Spend 5 minutes clarifying, 15 minutes designing, 10 minutes on failure modes, 5 minutes summarizing tradeoffs.

Day 7: Review recordings or notes. Cut filler phrases. Add crisp lines about idempotency, tenant boundaries, observability, and backward compatibility.

How to talk about API design like a senior engineer

Senior candidates explain both contract and consequences. Instead of saying “I’ll add rate limiting,” say “I’ll rate limit per API key and per tenant, return 429 with Retry-After, and expose remaining quota headers so clients can back off before they hit the wall.” Instead of saying “we need versioning,” say “I’ll treat field additions as backward compatible, never change enum semantics silently, and instrument old-version usage before deprecation.”

Close the interview with a recap: “The core design is REST for commands and retrieval, webhooks for async state, cursor pagination for lists, idempotency keys for writes, scoped auth for tenants, structured errors with request IDs, and additive versioning with a migration window.” That summary makes your answer feel complete.

If you can consistently move from product workflow to resource model to operational contract, API design interviews become predictable. The interviewer is not looking for the only correct endpoint list. They are looking for judgment: stable abstractions, safe retries, secure boundaries, and a contract that future teams will not hate.

Related guides

• Backend System Design Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps — A backend System Design interview cheatsheet for 2026 with the core flow, architecture patterns, capacity heuristics, reliability tradeoffs, and traps that separate senior answers from vague box drawing.
• Frontend System Design Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps — A practical Frontend System Design interview cheatsheet for 2026: how to structure the conversation, which patterns to reach for, what tradeoffs to name, and the traps that cost senior candidates offers.
• System Design Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps — A concise but practical system design interview cheatsheet for 2026 covering reusable patterns, example walkthroughs, a 7-day practice plan, and the traps to avoid.
• AWS Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps — A high-signal AWS interview cheatsheet for 2026 covering architecture patterns, IAM, networking, reliability, cost, debugging, and the answers that show real cloud judgment.
• Data Modeling Interview Cheatsheet in 2026 — Patterns, Examples, Practice Plan, and Common Traps — A practical Data Modeling interview cheatsheet for 2026 covering entities, relationships, relational and NoSQL patterns, analytics models, index choices, examples, and the traps that make otherwise strong candidates look shallow.