API Design Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric

API Design mock interview questions in 2026 test whether you can create interfaces that are usable, secure, evolvable, observable, and hard to misuse. The interviewer is rarely grading whether you know every REST convention. They want to see how you define resources, model workflows, handle errors, enforce auth, support versioning, manage idempotency, and keep clients stable as the product changes. This guide gives you realistic practice prompts, an answer structure, a scoring rubric, examples, drills, and a seven-day plan.

API Design mock interview questions in 2026: what interviewers look for

A strong API design answer balances developer experience and system constraints. You should be able to explain not only the endpoints, but also why the interface is safe for retries, how pagination works, what errors look like, how clients authenticate, and what happens when a long-running operation fails.

Key dimensions:

| Dimension | Strong signal | |---|---| | Resource modeling | Clear nouns, relationships, identifiers, and lifecycle | | Workflow design | Handles create, update, cancel, retry, async jobs, and webhooks | | Contracts | Stable request/response schemas, validation, and examples | | Reliability | Idempotency, pagination, rate limits, retries, and timeouts | | Security | Authentication, authorization, scopes, audit logs, and data minimization | | Evolution | Versioning, deprecation, backward compatibility, and migrations | | Operations | Observability, error taxonomy, supportability, and client SDK needs |

Many candidates stop after naming endpoints. Senior candidates discuss the contract around those endpoints.

A reusable answer structure

Use this for most API design prompts:

1. Clarify product requirements. Who are the clients, what actions do they need, and what scale or compliance constraints matter?
2. Model resources and lifecycle. Define entities, IDs, ownership, state transitions, and relationships.
3. Design endpoints or operations. Choose REST, RPC, GraphQL, or events based on use case. Show examples.
4. Define contracts. Include request schema, response schema, validation, error format, pagination, and filtering.
5. Handle reliability. Add idempotency keys, retries, async jobs, webhooks, rate limits, and eventual consistency behavior.
6. Secure it. Cover auth, authorization, scopes, tenancy boundaries, audit logs, and sensitive fields.
7. Plan evolution. Versioning, deprecation windows, compatibility rules, and observability.

This structure makes you sound like you design APIs that other teams can live with for years.

Practice question bank

1. Design an API for creating, refunding, and listing payments.
2. Design a public API for uploading files and processing them asynchronously.
3. Create an API for a calendar scheduling product with invitations and availability.
4. Design a webhook system for notifying customers about order status changes.
5. Design an API for feature flags used by mobile and backend clients.
6. How would you handle idempotency for a create-payment endpoint?
7. How do you design pagination for a large collection that changes during pagination?
8. When would you choose REST versus gRPC versus GraphQL?
9. Design error responses for validation, auth failure, rate limits, and dependency timeouts.
10. How do you version an API without breaking existing clients?
11. Design an API for multi-tenant organization and user permissions.
12. A client keeps retrying and creating duplicate records. What should the API do?
13. How would you design bulk operations with partial success?
14. What should be logged for audit without leaking sensitive data?
15. How do you deprecate a field used by 30% of clients?

For each prompt, practice drawing the resource model before writing endpoints.

Additional realistic practice prompts

Use these prompts to stretch beyond endpoint lists:

• Design an API for importing 100,000 contacts with validation errors and partial success.
• Design an API for usage-based billing where events arrive late or are duplicated.
• Design a permissions API for organizations, roles, service accounts, and audit logs.
• Design an API that lets customers rotate credentials without downtime.
• Design a search API for records that may be deleted, redacted, or permission-filtered.
• Design a mobile sync API that handles offline edits and conflict resolution.

For each, state the lifecycle first. The import API, for example, is not just POST /imports; it needs upload, validation, processing, per-row errors, retry, cancellation, completion, retention, and notification. The billing API needs idempotent event ingestion, event timestamps versus receipt timestamps, deduplication keys, correction events, and customer-visible auditability. These details show seniority because they anticipate how the API behaves after the happy path.

Strong answer example: payment API

Prompt: Design an API for creating, refunding, and listing payments.

Strong answer:

"I would start by clarifying whether this is a public merchant API, an internal service API, or both. For a public payment API, duplicate charges and authorization mistakes are high severity, so idempotency, auditability, and clear state transitions are central.

The core resources are Payment, Refund, Customer, and maybe PaymentMethod. A payment has an immutable ID, amount, currency, status, merchant account, customer reference, created time, and a set of events. Status could move from requires_confirmation to processing, succeeded, failed, canceled, or partially_refunded. I would avoid allowing arbitrary status updates from clients. State changes should happen through explicit operations.

Endpoint sketch: POST /v1/payments, GET /v1/payments/{payment_id}, GET /v1/payments?customer_id=...&status=...&created_after=..., POST /v1/payments/{payment_id}/refunds, and GET /v1/refunds/{refund_id}.

POST /payments requires an Idempotency-Key header. If a client retries with the same key and same parameters, return the original result. If the same key arrives with different parameters, return a conflict. The request should include amount in minor units, currency, customer or payment method token, and optional metadata. The response should include payment ID, status, next action if any, and links to related resources.

Refunds should also be idempotent. A partial refund requires amount and reason. The API must prevent refunding more than the captured amount, and it should return the updated payment state. For asynchronous processing, the API may return processing and send webhooks such as payment.succeeded, payment.failed, and refund.succeeded. Webhooks need signing, retry policy, event IDs, and an endpoint to list events so clients can recover missed notifications.

For errors, I would use a consistent shape: error code, message, parameter, request ID, and retryable boolean. Validation errors are 400, auth failures 401/403, conflicts 409, rate limits 429 with retry-after, and transient service errors 503. Every response should include a request ID for support.

Security includes OAuth or API keys scoped by merchant, least-privilege permissions, no raw card data, audit logs for sensitive operations, and tenant isolation on every query. For versioning, I would keep backward-compatible additions in v1 and reserve breaking changes for a dated or major version."

This answer is strong because it treats payment as a reliability and trust problem, not just CRUD.

Scoring rubric for API design interviews

| Score | Signal | |---|---| | 1 | Lists endpoints only, no lifecycle, errors, auth, or reliability | | 2 | Has basic REST resources but misses idempotency, pagination, or versioning | | 3 | Provides reasonable endpoints, schemas, errors, auth, and common edge cases | | 4 | Adds lifecycle, retries, async jobs, webhooks, observability, and compatibility | | 5 | Shows senior judgment around tradeoffs, abuse, operational support, client migration, and long-term maintainability |

To move from a 3 to a 4, add failure behavior. To move from a 4 to a 5, explain how clients recover from partial failure and how the API evolves safely.

Design details interviewers love

Idempotency. For operations with side effects, especially payments, orders, provisioning, and imports, support idempotency keys. Store the key, request fingerprint, response, and expiration. Return the same result on retry. Reject mismatched parameters.

Pagination. Prefer cursor pagination for large or changing datasets. Offset pagination is simple but can skip or duplicate records when data changes. Include next_cursor, limit caps, stable sorting, and filters.

Errors. Use stable machine-readable codes. Human messages can change, but codes become part of the contract. Include request IDs and retry hints.

Async jobs. For long-running work, return 202 Accepted with a job ID or resource in processing state. Provide status polling and optional webhooks. Define retention and cancellation behavior.

Webhooks. Include event IDs, timestamps, type, resource ID, signature, retry schedule, and replay endpoint. Tell clients to handle duplicates and out-of-order events.

Bulk operations. Decide whether the operation is atomic or partial success. Return per-item results. Avoid making clients guess what happened.

Versioning. Backward-compatible changes include adding optional fields or new enum values if clients are prepared. Breaking changes include renaming fields, changing meanings, removing fields, or tightening validation unexpectedly.

REST, RPC, GraphQL, and events

You do not need to be dogmatic. Use REST when resources and lifecycle are central and external developers need predictability. Use gRPC when low-latency internal service contracts, strong typing, and streaming matter. Use GraphQL when clients need flexible reads across a graph and you can manage authorization and query cost. Use event-driven APIs when consumers need to react to state changes asynchronously.

A senior answer says, "For the public merchant API I would use REST plus webhooks. Internally, the payment processor might use gRPC events." That shows pragmatic architecture.

Common traps

• CRUD-only design. Not every state change should be a generic update. Use explicit actions for confirm, cancel, refund, publish, archive, or approve.
• Leaky internal models. Do not expose database tables as API resources if they do not match the customer workflow.
• No retry story. Clients will retry. Design for it.
• Ambiguous errors. A generic 400 with a paragraph message is hard to automate against.
• Breaking clients casually. External APIs become commitments.
• Ignoring abuse. Rate limits, scopes, and audit logs matter in public APIs.

If the interviewer pushes back on complexity, explain which pieces are required for the risk level and which can be phased.

Failure modes to name explicitly

Strong API design candidates volunteer failure modes before the interviewer has to ask. Name what happens when a client retries after a timeout, sends the same idempotency key with different parameters, requests a page after items changed, receives webhooks out of order, loses permission halfway through a workflow, or calls an old version after a field is deprecated. Also explain what customers can observe: request IDs, event logs, status endpoints, replay APIs, and clear error codes.

A concise answer structure for any edge case is: detect the condition, return a stable machine-readable response, preserve safety, make recovery possible, and log enough context for support without exposing sensitive data. That pattern applies to payments, imports, provisioning, and admin APIs.

Seven-day prep plan

Day 1: Review REST resource modeling, status codes, errors, and pagination. Redesign one API you use often.

Day 2: Practice idempotency, retries, and async jobs. Design payment, import, and provisioning flows.

Day 3: Study auth and authorization: API keys, OAuth scopes, tenant isolation, audit logs, and sensitive fields.

Day 4: Practice webhooks and event delivery. Include signing, retries, replay, and duplicate handling.

Day 5: Compare REST, gRPC, GraphQL, and events. Prepare when you would use each.

Day 6: Do two full mock designs with schemas and error examples.

Day 7: Create a one-page checklist: resources, lifecycle, contracts, reliability, security, evolution, observability.

Final interview reminders

API design is interface design under uncertainty. Start with the developer's job, then make the contract explicit. Mention idempotency for side effects, cursor pagination for changing collections, signed webhooks for events, stable error codes for automation, and versioning for long-term trust. If your answer helps a client recover from failure, you are thinking at the right level for 2026 interviews.

Related guides

• Backend System Design Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric — Backend system design practice for 2026 with API, data, consistency, queueing, reliability, and operations prompts plus a senior-level scoring rubric.
• Design Critique Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric — Use this design critique prep guide to practice product, UX, and visual critique questions with a structured rubric, examples, drills, and a 7-day plan.
• Frontend System Design Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric — Frontend system design practice for 2026: component architecture prompts, answer structure, performance and accessibility rubric, drills, and strong/weak examples.
• Machine Learning System Design Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric — Machine learning system design interview practice for 2026 with prompts, model/serving architecture, metrics, monitoring, safety tradeoffs, and a scoring rubric.
• System Design Mock Interview Questions in 2026 — Practice Prompts, Answer Structure, and Scoring Rubric — A practical system design mock interview kit for 2026 with realistic prompts, a reusable answer structure, scoring rubric, drills, and strong-versus-weak examples.