API design questions.
81 api designquestions from the bank — open to read. Pick one and practice it out loud; a coach note comes back in seconds.
All 81 questions
Design the API for a service that creates and manages user-uploaded files. Walk me through the resource model and the key endpoints.Design a payment-initiation endpoint. How do you make it safe to retry without charging twice?Walk 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?Design the error responses for an API that accepts a complex JSON object. How do you tell the client what's wrong without leaking implementation?Design pagination for a list endpoint that returns events in chronological order. The data grows constantly. What's your story?Design how rate limits are surfaced to API clients. What headers, what behavior on 429, what gets communicated when?An older client sends a field you no longer accept. What does your API do, and what does it not do?Design the API for a notification preferences service that supports per-channel, per-category opt-ins.Design a CREATE endpoint that callers may retry on network errors. Walk me through the contract you'd offer.What's the right way to surface a partial-failure response — for example, a bulk operation where 9 of 10 items succeeded?Your team is debating URL versioning vs header versioning for a new public API. Walk me through the trade-offs and pick one.Design 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.A customer needs to walk every object in a collection of 50 million records via your API. What's your strategy?How would you design rate limits that are fair across customers but allow controlled bursts for verified ones?You need to add a required field to an existing object that callers create. How do you roll that out without breaking clients?Design the API for a multi-tenant analytics service. What makes the surface clean for both an admin and an end-user persona?Two endpoints can return 'not found' for very different reasons. How do you make those distinguishable without leaking internals?Design an authentication API for third-party developers to call on behalf of users. What grants, what tokens, what lifetimes?A field in your API was nullable but is now always populated. Is that a breaking change? Walk me through your reasoning.Design an API for a calendar service that other services use for booking and querying availability.How would you structure rate-limit responses so a smart client can degrade gracefully rather than hammer?Design a search API that supports filter, sort, and free-text queries. How do you keep it from sprawling?Walk me through how you'd design retryable versus non-retryable error responses. What guidance do you give clients?An API endpoint returns a list that some customers want sorted by created_at and others want by updated_at. How would you handle that?Design the API for an inbox: read, mark-read, archive, and search. Multi-device sync matters.An SDK calls deprecated endpoints. You want clients to migrate. What do you change about the API itself to push migration?Should DELETE be idempotent in your API? Walk me through both directions and what you'd actually ship.Design the API for a long-running export job. The job can take minutes. How does the caller know when it's done?Validation errors in an API often pile up. How do you return all of them in one response in a way clients can act on?Design the API for a comment system on a third-party platform — threading, edit history, moderation hooks.Design 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?You'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?Your 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?A 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?Design 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?Your 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?You'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?Design 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?A user clicks 'submit order' twice because the page was slow. How would you design the order creation endpoint to handle this gracefully?You 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?A 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?You'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?Design 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?Your 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.Your 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?Two 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.Design 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?A teammate says PUT and PATCH are interchangeable since both update a resource. Where do they actually differ, and when does the difference bite?When 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.You'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?Your 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?Mobile 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?Product 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?Design API-key management for a public API: issuance, scoping, rotation, and revocation. What makes rotation something customers actually do instead of fear?Your 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?You'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?Design 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?You'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.Design an API endpoint that returns large binary files (videos, datasets). How do you handle range requests, resumable downloads, and communicate file metadata?Your 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?Design 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?You 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.Design 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?Your 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?Design 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?A 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.Design 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?You'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?Design 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?Your 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?Design 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?You'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?Design 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?A 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?Design 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?Your 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.You'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?Design 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?Your 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?Design 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?You'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?