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.
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 line | What to decide | Example |
|---|---|---|
Name | Verb and path for a request, or a past-tense name for an event |
|
Inputs | The two or three fields that drive the design, plus any header that matters |
|
Output | The resource or the id, and the status code when it isn't the obvious one |
|
Failure and retry | What a repeat of the same request does; what a stale cursor does | Second |
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.
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, analyticsWrites 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.
Pairs with Core entities and the data model before it and Walking one request through the design after it.
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)orget(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
| Decision | Simpler option | When the simpler one is right | Heavier option | When 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 | Internal tools, or where a duplicate is cheap and visible to the user |
| 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 | 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 |
| 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 |