Skip to content

Designing the API in an interview

The step in a system design round where you turn the requirements into three to five endpoints or events, each with its inputs, output and retry behavior. It fixes the contract the rest of the design has to honor.

On this page

What it is

The API step is where a system design answer stops being a list of requirements and becomes a contract: the handful of operations a client can call, what each takes, what it returns, and what happens when it fails or is repeated. Google's API design guidance (its AIPs) orders the work as resources first, then the relationships between them, then each resource's schema, then the methods, leaning on the standard verbs (Get, List, Create, Update, Delete) and adding a custom method where none of those fits. The same guidance warns against an API that mirrors the database schema: the two have different jobs, and tying them together couples the surface to the storage.

In a round the skill is choosing. Our advice: take each functional requirement and write the one call that satisfies it, and aim for three to five lines in total. Each call gets a line, not a paragraph: the verb and path or the event name, the two or three inputs that matter, the shape of the response, and one note about failure. That line is what you point at later when you trace a request through the boxes.

Part of the lineWhat to decideExample

Name

Verb and path for a request, or a past-tense name for an event

POST /v1/reservations, reservation.confirmed

Inputs

The two or three fields that drive the design, plus any header that matters

event_id, seat_ids[], Idempotency-Key

Output

The resource or the id, and the status code when it isn't the obvious one

201 Created with the resource and its URL; 202 Accepted when work finishes later; 204 No Content on delete

Failure and retry

What a repeat of the same request does; what a stale cursor does

Second POST with the same key returns the first response

Caller

Which client or service calls it, and how often

Mobile app when a user taps a seat; the rate from your earlier estimate

The status codes in the table are the ones Microsoft's Azure REST guidelines set for each method: 201 with the new resource's URL when a POST creates something, 202 when a PUT, POST or DELETE finishes asynchronously, 204 without a body for DELETE. You don't have to recite them, but writing 202 beside a slow call shows you've thought about where the client waits.

text
An example: a seat reservation service, as it might sit beside the diagram

POST /v1/reservations                 Idempotency-Key: <uuid>
  in:  event_id, seat_ids[]
  out: 201 {reservation_id, status: held, expires_at}

POST /v1/reservations/{id}:confirm    (payment token in body)
  out: 200 {status: confirmed}   or 202 + job id if payment is slow

GET  /v1/reservations/{id}
  out: 200 {reservation}

GET  /v1/events/{id}/seats?cursor=&limit=50
  out: 200 {seats[], next_cursor}

event reservation.confirmed {reservation_id, user_id, seat_ids}
  consumers: notifications, analytics

Writes and retries. A client that times out on a create request has no way to know whether it landed, so it retries, and the API has to make that retry harmless. Stripe's documentation describes the common mechanism: the client generates a unique key (a random UUID is suggested) and sends it with the request; the server stores the first response (status code and body) under that key and answers later requests carrying the same key with the stored response. In Stripe's v1 API that saved result is kept for at least 24 hours, and a retry whose parameters differ from the original is rejected rather than served. The keys go on POST; GET and DELETE are treated as idempotent already. Microsoft's guidelines take the same position from the other side: all operations, POST included, should be idempotent, and one way to get there is to create with PUT or PATCH so the client names the resource and a repeat has the same effect as the first request.

Lists. Any call that returns many items needs a paging decision, and the choice depends on how the list behaves. Slack's engineering write-up of its own API lays out the trade: offset paging (page number and count) is simple, shows totals and lets a client jump to page twelve, but the database still reads and then discards the skipped rows, and when items are inserted at the head between requests the next page repeats or skips items. Cursor paging returns a pointer to the last item and the next request continues after it, which holds up on large and fast-changing lists, at the cost of no total count and no jumping; it also needs a unique, ordered column to point at. One implementation detail worth knowing: Slack fetches one row more than the requested count and uses that extra row's id as the next cursor, so an under-full page signals the end.

Slow work and events. When a request starts something that takes longer than a client should wait (encoding a video, running a payment, generating a report), the server returns 202 Accepted and treats the work as a long-running operation the client can check on. In the round, that means the call returns an id, and you add a GET on that id or an event the client subscribes to. Events belong on your list alongside endpoints when another part of the system reacts to a change: name the event, its payload and who consumes it, the same way you'd name a request.

When to use it

Do it right after the functional requirements and the core entities, before the high-level diagram, because the diagram's arrows are these calls. Each endpoint becomes the label on an arrow from client to service, and each event becomes the arrow out of a service into a queue or a consumer. If you draw boxes first, you end up inventing the contract while explaining the picture, and the two drift apart.

Spend more time here when the hard part of the problem lives in the contract: a client that will retry (payments, bookings, anything that creates money or scarcity), a list that grows while people read it (feeds, chat history, search results), or an operation that takes minutes (uploads, encoding, exports). In those rounds the API line is where you show you've seen the problem, and the components later are mostly the consequence of what you wrote here.

When not to

Our advice for the cases where less is more:

  • The interviewer asks you to assume a standard API. Write a line, offer to come back if a call turns out to matter, and move to the diagram.
  • The question is a single component. For a rate limiter or a cache, keep the interface short (a call like allow(key) or get(key), plus whatever the requirements add) and put the depth into the algorithm and the storage.
  • CRUD on each entity. Listing Get, List, Create, Update and Delete for each noun spends time without making a decision, and it hides the few calls that do. Write the calls the requirements need; mention that the rest are standard.
  • The transport debate. Which protocol or query style to use is a discussion for when the interviewer asks or when a requirement forces it (a browser client, a streaming response, a mobile client on a weak network). Otherwise pick in a sentence and spend the time on the decisions above: retries, paging and slow work still have to be settled whatever the transport.
  • Field-by-field schemas. Full request and response bodies belong in a design document. In the room, the fields that change a decision (the idempotency key, the cursor, the id you poll) are enough.

Compared

DecisionSimpler optionWhen the simpler one is rightHeavier optionWhen it earns its cost

Paging a list

Offset: page number and count

Small or slow-changing lists, admin tables where users want totals and to jump to a page

Cursor: pointer to the last item, plus a limit

Large lists, or lists with inserts at the head while people scroll (feeds, messages)

Creating something

Plain POST, server picks the id

Internal tools, or where a duplicate is cheap and visible to the user

POST with a client idempotency key, or PUT to a client-chosen id

Anything a client retries after a timeout and a duplicate costs money or a seat

An action on a resource

Standard update of a state field

When the change is a plain field write with no side effects

Custom method such as :confirm or :cancel

When the action runs logic, touches other systems or has to be audited as a step

Work that takes a while

Synchronous response, client waits

Sub-second work, or a one-off script where blocking is fine

202 Accepted with an id to poll, or an event when it finishes

Minutes-long work, mobile clients, anything the user shouldn't sit through

How much to write in the round

One line: "standard CRUD on these entities"

When the interviewer says so, or the problem is one component

Three to five written calls with inputs, output and retry behavior

When the contract holds the hard problem: retries, paging, slow work

In a picture

listsslowRequirementsPick 3-5 callsInputs, outputRetry behaviorCursor paging202 or eventLabel the arrows
From requirements to a short list of calls, each with its retry, paging and slow-work decision, which then label the diagram's arrows.

How to say it in an interview

The common mistake

Quiz

A mobile client sends POST /orders, the connection drops before the response arrives, and the app retries. Which API decision keeps the user from being charged twice?
You're designing the API for a chat channel's message history. New messages arrive constantly while a user scrolls back. Which paging style fits, and why?
An internal admin screen lists a few thousand accounts, rarely changes, and the support team wants to jump to a page and see the total. What do you write?
Uploading a video kicks off encoding that takes several minutes. How should the upload call respond?

Related

Sources

  1. AIP-121: Resource-oriented design (Google API Improvement Proposals)
  2. Idempotent requests (Stripe API reference)
  3. Evolving API Pagination at Slack (Slack Engineering)
  4. Microsoft Azure REST API Guidelines (microsoft/api-guidelines on GitHub)
Sign in to report a mistake