API Design Interview Questions: 10 Worked Answers and a Method

An API design interview asks you to define a contract, not build a system. You get a product in one sentence. From that you produce the resources, the endpoints, the request and response shapes, and the rules for failure. No database sharding, no capacity maths, no load balancer diagram.

The ten questions below come up most often. Each one lists the resources to name, the endpoints to write, and the trade offs the interviewer is waiting for.

How this round differs from system design

Some companies run this as a separate round. Stripe, Twilio, Shopify, Plaid, and Square are the well known ones, because for them the API is the product. At other companies it appears as one section inside a broader system design interview.

The six step method

Use the same order every time. It is what stops you from designing endpoints for a product you have not understood yet.

1. Requirements. Who calls this, and what are they trying to do? Public or internal changes every later answer.
2. Resources. Pull the nouns out of the operations. Resist inventing endpoints at this stage.
3. Endpoints. Plural nouns for collections, HTTP methods for actions, no verbs in paths.
4. Payloads. What the client sends, what the server owns, what comes back.
5. The hard parts. Retries, pagination, errors, auth, rate limits.
6. Change. Versioning and deprecation, said out loud before you are asked.

Interviewers grade the order as much as the output. Saying which step you are on is free marks.

1. Design a URL shortener API

Resources: links. Optionally analytics as a sub resource.

POST   /v1/links            Create a short link
GET    /v1/links/{code}     Read its metadata
DELETE /v1/links/{code}     Deactivate it
GET    /{code}              The redirect itself

The trade offs to raise: the redirect is not a JSON endpoint, so it returns 301 or 302 and lives outside the /v1 namespace. Permanent redirects get cached by browsers forever, which breaks analytics, so 302 is usually the right answer. Custom aliases need a uniqueness check that returns 409 rather than silently overwriting.

2. Design a payment API

Resources: payments, refunds, customers, payment methods.

POST /v1/payments               Charge a customer
GET  /v1/payments/{id}          Read one payment
POST /v1/payments/{id}/refund   Refund it
POST /v1/customers              Create a customer

Three things make this a payment API rather than CRUD. Retries must not double charge, so accept an Idempotency-Key header on the create. Some payments are slow, so decide between 202 Accepted plus a webhook and blocking for the final status. Errors need stable machine readable codes, because a client has to branch on insufficient_funds rather than parse a sentence.

Never let the client set the amount status or the payment id. Those belong to the server.

3. Design a chat API

Resources: conversations, messages, participants.

POST /v1/conversations                       Start one
GET  /v1/conversations/{id}/messages         History, paginated
POST /v1/conversations/{id}/messages         Send

The real question is delivery. History is a normal paginated GET. Live messages are not. Name the options: WebSockets for a two way stream, server sent events for one way push, and long polling as the fallback. Say which you would pick and why.

Then handle the client that sends the same message twice on a flaky connection. A client generated message id makes the send idempotent and doubles as the local ordering key.

4. Design a booking API

Resources: listings, availability, bookings.

GET  /v1/listings/{id}/availability?from=&to=
POST /v1/bookings
POST /v1/bookings/{id}/cancel

The trade off is holding inventory. Two people can book the last room at the same moment. Either you create the booking optimistically and return 409 to the loser. Or you add a short lived hold resource that reserves the slot while payment completes.

A hold is more honest for anything that takes a user several steps. Say how long it lives and what releases it.

5. Design a feature flag API

Resources: flags, environments, targeting rules.

GET  /v1/flags                     All flags for the caller
GET  /v1/flags/{key}/evaluate      Resolve one flag for one user
PUT  /v1/flags/{key}               Update the rule

The interesting part is read volume. Every request in every service may check a flag, so a per call round trip is not acceptable. The usual answer is a bulk fetch plus local caching, with a stream or a poll to invalidate. Say what happens when the flag service is unavailable: the client falls back to the last known values, not to an error.

6. Design a checkout API

Resources: carts, line items, orders.

POST   /v1/carts
POST   /v1/carts/{id}/items
DELETE /v1/carts/{id}/items/{itemId}
POST   /v1/carts/{id}/checkout      Turns the cart into an order

Checkout is where the cart stops being editable, so it is a state transition rather than an update. Prices can change between adding an item and paying, so decide whether the cart snapshots the price or reprices at checkout. Both are defensible. Not noticing the problem is not.

7. Design a calendar API

Resources: calendars, events, attendees.

GET  /v1/calendars/{id}/events?from=&to=
POST /v1/calendars/{id}/events
PATCH /v1/events/{id}

Recurring events are the whole question. Storing every occurrence explodes the data. Storing a rule means every read has to expand it. The usual answer is a rule plus a small set of exceptions for edited or deleted occurrences.

Then say how a client edits one occurrence of a series, because that is the follow up. The API needs a way to say "this one", "this and future", or "all".

8. Design a file storage API

Resources: files, folders, upload sessions.

POST /v1/uploads                 Start an upload, get an id and a URL
PUT  /v1/uploads/{id}/parts/{n}  Send one part
POST /v1/uploads/{id}/complete   Finish
GET  /v1/files/{id}/content      Download

Do not send bytes through a JSON API. Issue a pre signed URL and let the client talk to storage directly, so your service is not a proxy for gigabytes.

Large uploads need to resume, so parts get numbered and the client can ask which parts already landed. Downloads should support range requests so a paused video can continue.

9. Design a ride sharing API

Resources: riders, drivers, ride requests, trips.

POST /v1/rides                   Request a ride
GET  /v1/rides/{id}              Status
POST /v1/rides/{id}/cancel
POST /v1/drivers/{id}/location   Driver location update

Two things separate a good answer. Location updates are high frequency and low value individually, so they should be cheap, batched, and probably not a REST call per ping. And a ride moves through states. So the API needs a status field with a documented set of values, plus a rule for which transitions are legal.

Cancellation has money attached, which means it needs its own rules rather than being a DELETE.

10. Critique this API

Some interviewers hand you a bad API and ask what is wrong. Work down a fixed list.

• Verbs in paths, such as /getUser or /createOrder.
• 200 returned for errors, with the failure hidden in the body.
• Inconsistent naming: userId here, user_id there.
• No pagination on a list endpoint.
• No version, or a version nobody routes on.
• Passwords or tokens in query strings.
• Errors with no stable code, only English text.
• A GET that changes data.

Say what you would change and why it matters to a caller. Listing faults without consequences reads as pedantry.

What gets you rejected

• Writing endpoints before asking who calls the API.
• Treating it as a database schema question.
• Ignoring retries, then having no answer on double charges.
• Designing for one screen, so the API breaks when the screen changes.
• Silence about versioning until the interviewer asks.
• Reciting REST constraints without saying what they buy the caller.

Frequently asked questions

What is an API design interview?

A round where you define an API contract from a short product brief. You produce resources, endpoints, request and response shapes, error behaviour, and rules for pagination, versioning, and retries. There is usually no coding.

How do I prepare for an API design interview?

Learn one repeatable method and run it on six or seven problems out loud. Resources before endpoints, then payloads, then the failure cases. Being able to name a trade off matters more than memorising any particular endpoint list.

Which companies ask API design questions?

API first companies most of all: Stripe, Twilio, Shopify, Plaid, and Square. Larger companies fold it into a system design round, especially for backend and platform roles.

Is API design the same as system design?

No. System design asks how the system holds up under load. API design asks whether the contract is usable, consistent, and safe to change. Scale only enters an API answer where it changes the contract, such as pagination or rate limits.

How long is an API design interview?

Usually 45 to 60 minutes. That is enough for requirements, a resource model, six to ten endpoints, and a discussion of two or three hard parts. It is not enough to design everything, so choose depth over coverage.

What should I say first in an API design round?

Ask who calls the API and what they are trying to do. A public API for outside developers and an internal service API lead to different answers on versioning, errors, and rate limits. Starting there signals that you have shipped one.

Where to go next

The method above is the short version. Grokking Modern API Design Interview teaches it in full. It works 15 complete designs end to end, including the payment, chat, booking, calendar, and file storage questions above. Several of its lessons are free to read, including a framework for API design answers and idempotency keys.

For the surrounding round, Grokking the System Design Interview covers the framework and the building blocks that strong API answers reference.

Related Reading

• API interview questions
• How to design a RESTful API
• API design best practices
• The API design checklist
• Types of system design interviews