API design questions.

81 api design questions from the bank, ready to practice out loud.

Learn the ideas first · free with an account

STAR and CARL: structuring your story Making a write safe to retry Showing depth without lecturing Changing an API people already use

All 81 questions

File upload service API designDesign the API for a service that creates and manages user-uploaded files. Walk me through the resource model and the key endpoints.Interface designMid–senior

Idempotent payment initiation endpointDesign a payment-initiation endpoint. How do you make it safe to retry without charging twice?IdempotencySenior–staff+

Breaking changes in public APIsWalk me through how you'd evolve a public API to add a breaking change to a flagship resource. What's your story for existing clients?VersioningSenior–staff+

Error responses for complex JSONDesign the error responses for an API that accepts a complex JSON object. How do you tell the client what's wrong without leaking implementation?Error semanticsMid–senior

Paginating growing event streamsDesign pagination for a list endpoint that returns events in chronological order. The data grows constantly. What's your story?PaginationMid–senior

Surfacing rate limits to clientsDesign how rate limits are surfaced to API clients. What headers, what behavior on 429, what gets communicated when?Rate limitingMid–senior

Handling deprecated request fieldsAn older client sends a field you no longer accept. What does your API do, and what does it not do?Backward compatibilityMid–senior

Notification preferences API designDesign the API for a notification preferences service that supports per-channel, per-category opt-ins.Interface designMid–senior

Idempotent CREATE endpoint contractDesign a CREATE endpoint that callers may retry on network errors. Walk me through the contract you'd offer.IdempotencyMid–senior

Partial failure in bulk operationsWhat's the right way to surface a partial-failure response — for example, a bulk operation where 9 of 10 items succeeded?Error semanticsSenior–staff+

URL versioning vs header versioningYour team is debating URL versioning vs header versioning for a new public API. Walk me through the trade-offs and pick one.VersioningSenior–staff+

Webhooks system designDesign the API for a webhooks system. Subscribers want to know what changed, and at what time, and they need to be able to confirm authenticity.Interface designSenior–staff+

Iterating through 50 million recordsA customer needs to walk every object in a collection of 50 million records via your API. What's your strategy?PaginationSenior–staff+

Fair rate limits with burstsHow would you design rate limits that are fair across customers but allow controlled bursts for verified ones?Rate limitingSenior–staff+

Adding required fields without breakingYou need to add a required field to an existing object that callers create. How do you roll that out without breaking clients?Backward compatibilityMid–senior

Multi-tenant analytics API designDesign the API for a multi-tenant analytics service. What makes the surface clean for both an admin and an end-user persona?Interface designSenior–staff+

Distinguishing different not found casesTwo endpoints can return 'not found' for very different reasons. How do you make those distinguishable without leaking internals?Error semanticsMid–senior

Third-party OAuth API designDesign an authentication API for third-party developers to call on behalf of users. What grants, what tokens, what lifetimes?Interface designSenior–staff+

Nullable field becoming always populatedA field in your API was nullable but is now always populated. Is that a breaking change? Walk me through your reasoning.VersioningSenior–staff+

Calendar booking and availability APIDesign an API for a calendar service that other services use for booking and querying availability.Interface designMid–senior

Rate limit response designHow would you structure rate-limit responses so a smart client can degrade gracefully rather than hammer?Rate limitingSenior–staff+

Search API without sprawlDesign a search API that supports filter, sort, and free-text queries. How do you keep it from sprawling?Interface designSenior–staff+

Retryable vs non-retryable errorsWalk me through how you'd design retryable versus non-retryable error responses. What guidance do you give clients?Error semanticsMid–senior

Flexible sorting on list endpointsAn API endpoint returns a list that some customers want sorted by created_at and others want by updated_at. How would you handle that?PaginationMid–senior

Multi-device inbox API designDesign the API for an inbox: read, mark-read, archive, and search. Multi-device sync matters.Interface designSenior–staff+

Forcing SDK migrationAn SDK calls deprecated endpoints. You want clients to migrate. What do you change about the API itself to push migration?Backward compatibilitySenior–staff+

DELETE endpoint idempotencyShould DELETE be idempotent in your API? Walk me through both directions and what you'd actually ship.IdempotencyMid–senior

Long-running export job pollingDesign the API for a long-running export job. The job can take minutes. How does the caller know when it's done?Interface designMid–senior

Returning multiple validation errorsValidation errors in an API often pile up. How do you return all of them in one response in a way clients can act on?Error semanticsMid–senior

Comment system API with threadingDesign the API for a comment system on a third-party platform — threading, edit history, moderation hooks.Interface designSenior–staff+

REST API for to-do listDesign a simple REST API for a to-do list service. What resources would you expose, and what HTTP methods would you use for creating, reading, updating, and deleting tasks?Interface designEntry–mid

Handling duplicate email update requestsYou're designing an endpoint that lets users update their email address. What happens if the same request is sent twice by accident? How do you prevent unintended side effects?IdempotencyEntry–mid

Versioning a split name fieldYour API currently returns user objects with 'name' as a single field. You want to split it into 'first_name' and 'last_name'. How would you version this change?VersioningEntry–mid

Invalid JSON error responseA client sends a POST request with invalid JSON to your API. What HTTP status code should you return, and what information should be in the response body?Error semanticsEntry–mid

Paginating large blog archivesDesign a GET endpoint that returns a list of blog posts. The blog has thousands of posts, so you can't return them all at once. What parameters would you add to handle this?PaginationEntry–mid

Rate limit exceeded responseYour API allows 100 requests per minute per user. What HTTP status code should you return when a user exceeds this limit, and what should you include in the response?Rate limitingEntry–mid

Adding optional phone number fieldYou're adding a new optional field 'phone_number' to the user profile endpoint. Older clients won't send this field. Is this a breaking change? Why or why not?Backward compatibilityEntry–mid

Profile picture upload endpointDesign an endpoint for uploading a profile picture. What should the HTTP method be, what does the URL look like, and what should a successful response include?Interface designEntry–mid

Preventing duplicate order submissionsA user clicks 'submit order' twice because the page was slow. How would you design the order creation endpoint to handle this gracefully?IdempotencyEntry–mid

Deprecating an API versionYou need to remove support for API version 1 because it's insecure. How much notice should you give clients, and what should you return when v1 endpoints are called after deprecation?VersioningEntry–mid

Missing required price field errorA client sends a request to create a new product but forgets to include the required 'price' field. What status code and error message would you return?Error semanticsEntry–mid

Page numbers vs limit offsetYou're building an endpoint that lists transactions. Should you use page numbers (page=1, page=2) or limit/offset (limit=20&offset=40)? What are the basic trade-offs?PaginationEntry–mid

Streaming token-by-token responsesDesign the contract for an endpoint that streams a model-generated answer token by token. How do clients consume it, and what does the contract say when generation fails halfway through?Interface designSenior–staff+

Rate limiting expensive model requestsYour API fronts an expensive language-model backend, and one request can cost 100x another depending on input size. Requests-per-minute limits no longer protect you. Design limits that do.Rate limitingSenior–staff+

Versioning model behavior changesYour API exposes a model whose behavior shifts every time you retrain it, even though the request and response schemas never change. Integrators want stable behavior. How do you version that?VersioningSenior–staff+

Preventing concurrent update conflictsTwo clients PATCH the same resource at nearly the same moment and the second silently wipes out the first's change. Design the mechanism your API offers to prevent this.Concurrency controlMid–senior

Bulk import with validation feedbackDesign the API for a bulk import that accepts files with up to a million rows. Customers shouldn't wait an hour to learn that row 3 was malformed. What's the contract?Interface designSenior–staff+

PUT versus PATCH semanticsA teammate says PUT and PATCH are interchangeable since both update a resource. Where do they actually differ, and when does the difference bite?Interface designEntry–mid

Choosing between 401 and 403When an authenticated request fails, how do you choose between returning 401 and 403? Give a concrete example of each and what a well-behaved client does differently in response.Error semanticsEntry–mid

Multi-currency price representationYou're designing the response shape for prices in multiple currencies. What type does the amount field use, what travels alongside it, and what do you explicitly forbid?Interface designMid–senior

Idempotent SMS through third partyYour endpoint sends an SMS through a third-party provider that offers no idempotency support, and your callers retry on timeouts. How do you keep one logical request from sending three texts?IdempotencySenior–staff+

Fetching related resources efficientlyMobile clients need three sequential calls to render one screen and they're complaining. How would you let them fetch related resources in one round trip without rebuilding the API as GraphQL?Interface designSenior–staff+

Total count on huge tablesProduct wants every paginated list response to include total_count. The biggest table has 200 million rows and most lists are filtered. What are the options, their costs, and what do you ship?PaginationSenior–staff+

API key management and rotationDesign API-key management for a public API: issuance, scoping, rotation, and revocation. What makes rotation something customers actually do instead of fear?Auth and credentialsSenior–staff+

Scheduling across time zonesYour scheduling API accepts appointment times from clients in 40 countries, including recurring weekly events. How are times represented in the contract, and what do you reject at the boundary?Interface designMid–senior

Path versus query string designYou're adding an endpoint that fetches a user's orders filtered by status. What belongs in the URL path versus the query string, and what's the reasoning?Interface designEntry–mid

Multi-tenant data isolationDesign the API for a multi-tenant SaaS application where each tenant has isolated data. How do you model tenant context in requests, and what safeguards prevent cross-tenant data leakage?Auth and credentialsMid–staff+

Partial updates with null semanticsYou're designing a PATCH endpoint that allows partial updates to a complex nested resource. How do you distinguish between 'set to null' and 'leave unchanged'? Walk through your wire format.Interface designMid–senior

Serving large binary filesDesign an API endpoint that returns large binary files (videos, datasets). How do you handle range requests, resumable downloads, and communicate file metadata?Interface designMid–senior

Stale ETag conflict resolutionYour API uses optimistic concurrency control with ETags. A client sends an If-Match header with a stale ETag during an update. What status code and response body do you return, and why?Concurrency controlMid–senior

Validating optional filter combinationsDesign a search or filter endpoint that accepts a dozen optional query parameters. How do you validate combinations, communicate invalid filters, and avoid breaking clients when you add new filters?Error semanticsMid–senior

Deprecating active endpointsYou need to deprecate an API endpoint that still receives 15% of total traffic. Walk me through your deprecation timeline, client communication strategy, and the headers or responses you'd use.Backward compatibilitySenior–staff+

API keys versus OAuth 2.0Design the authentication flow for a public API offering both API keys and OAuth 2.0. When would you recommend each, and how do you communicate which scopes or permissions are missing?Auth and credentialsMid–senior

Trading data rate limit headersYour API serves real-time trading data with strict rate limits per user tier. A client hits the limit mid-day. What rate-limit headers do you return, and how do you let them know when quota resets?Rate limitingMid–senior

Cursor stability in dynamic feedsDesign cursor-based pagination for a social feed that users can scroll indefinitely. The feed is personalized and changes as new content arrives. How do you keep cursors stable?PaginationSenior–staff+

DELETE idempotency semanticsA client calls your DELETE endpoint twice with the same resource ID. The first call succeeds; what does the second return? Walk through idempotency semantics for DELETE.IdempotencyEntry–mid

Batch processing with partial failuresDesign an endpoint that accepts a batch of up to 100 items for processing. Some may fail validation while others succeed. How do you structure the response, and what HTTP status code do you use?Error semanticsMid–senior

Adding required fields safelyYou're adding a new required field to an existing API request schema. How do you roll this out without breaking clients still using the old schema? What's your migration path?Backward compatibilityMid–senior

Long-running asynchronous jobsDesign the API contract for a long-running asynchronous job (e.g., report generation, data export). How does the client check status, retrieve results, and handle failures?Interface designMid–senior

Content negotiation and format supportYour API supports both JSON and XML response formats via content negotiation. A client sends an Accept header you don't support. What do you return, and how do you communicate available formats?Error semanticsEntry–mid

API versioning strategyDesign an API versioning strategy for a platform with mobile apps that users rarely update. Compare date-based, URI, and header versioning. Which do you choose and why?VersioningSenior–staff+

GraphQL versus REST trade-offsYou're designing a GraphQL API alongside your REST API. A product manager asks which clients should use which. How do you decide, and what are the trade-offs for your team?Interface designSenior–leadership

Rate limiting across user tiersDesign rate limiting for a free tier with 1,000 requests/day and a paid tier with 100,000/day. How do you handle bursts, communicate limits, and prevent one user from starving others?Rate limitingMid–senior

Preventing lost concurrent updatesA client is updating a resource that another client modified moments ago. You need to prevent lost updates. Compare ETags, version numbers, and last-modified timestamps. What do you implement?Concurrency controlMid–senior

Idempotency for financial transfersDesign the idempotency mechanism for a money transfer API. Should you use idempotency keys, and if so, how long do you store them? What happens if a client reuses a key with different parameters?IdempotencySenior–staff+

Filtering transactions by date rangeYour API returns a list of transactions that can be filtered by date range, amount, and status. Design a URL structure and explain how you validate that the date range isn't too broad.Interface designEntry–mid

Migrating from SOAP to RESTYou're replacing a legacy SOAP API with REST. Existing clients expect detailed fault codes. How do you design error responses that satisfy both old expectations and modern REST conventions?Error semanticsSenior–staff+

Webhook delivery and replayDesign an API that allows clients to subscribe to webhooks for resource changes. How do you verify endpoint ownership, handle delivery failures, and let clients replay missed events?Interface designSenior–staff+

Refresh token expiration strategyYour API uses OAuth 2.0 with refresh tokens. A client's refresh token is about to expire. How do you communicate this in advance, and what's your rotation strategy?Auth and credentialsMid–senior

Offset pagination at scaleDesign offset-based pagination for a product catalog API. The catalog has 500,000 items and is updated frequently. What are the pitfalls, and when would you recommend cursor-based instead?PaginationMid–senior

Running two API versionsYou're launching API v2 with breaking changes while v1 remains supported. How do you route traffic, share infrastructure, and ensure both versions can coexist for 18 months?VersioningStaff+–leadership