DEV Community

Cover image for API design for system design interviews, explained
Gowtham Potureddi
Gowtham Potureddi

Posted on

API design for system design interviews, explained

API design for system design interviews, explained

Almost every system design interview has a step where you define the API — the contract between the client and your system — and it is where a surprising number of candidates get sloppy. API design is not "list some endpoints"; it is a set of deliberate choices about how you model resources, how a client pages through millions of rows, how versions evolve, and what happens when a request is retried after a timeout. An interviewer can tell in thirty seconds whether you have a vocabulary for those choices or whether a vague getStuff() is where your thinking stops. A good API is predictable, hard to misuse, and safe under the one condition the network guarantees: that requests will fail and clients will retry.

The reason this comes up in almost every round is that the API sits between everything — it is the first thing the client touches and the thing every later decision has to honour. Get the resource model and the pagination right and the rest of the design has clean seams; get them wrong and you are patching leaks for the rest of the hour. This guide walks the choices a strong candidate names out loud: REST resource modelling with the right HTTP methods and status codes, pagination (why cursor beats offset at scale) with filtering and versioning, and the reliability concerns — idempotency keys, rate limiting, and auth — that the follow-up questions are really about.

Title card for a system design interview explainer on API design, showing a clean REST resource with HTTP methods on one side and a cursor-paginated list with an idempotency key on the other, on a dark citrus-and-lavender background.

Why API design comes up in system design interviews

Defining the API is usually step three of a high-level design, right after requirements and estimation. It rarely gets its own prompt, but it is where the interviewer checks whether you think like someone who has maintained a system other people build on. You write POST /order, and the interviewer leans in: not whether you have an endpoint, but how it behaves — what it returns, how a client lists a million of them, and what happens when the client times out and sends it again. API design is a favourite probe precisely because a plausible-looking endpoint can hide a retry bug that corrupts data.

The interviewer rarely lets a create endpoint stand on its own. "The client calls POST /payment, the network times out, and the client retries. Walk me through exactly what happens — and how you make sure the user is not charged twice." That question — idempotency under retries — is the one a memorised list of endpoints can never survive, and the one this topic is really testing.

The rounds on Zynter are modelled on how the loop runs, not scraped from any candidate's recall. What matters for prep is the shape: you name an endpoint, and the next sentence out of the interviewer's mouth attacks its weakest point — a retry, a huge list, a breaking change, or an abusive client.

What the interviewer is really testing

An API answer is read on the same four dimensions as any design decision. Problem solving — did you model clean resources and make writes safe to retry, or bolt verbs onto URLs? Communication — can you say in one sentence why cursor pagination beats offset at scale? Technical execution — do you use the right methods and status codes, idempotency keys, and a sane versioning and rate-limiting story? Time management — did you spend your words on pagination and idempotency, the parts that actually break, not on bikeshedding URL casing? Reading this guide teaches the vocabulary; it does not teach you to defend an API while someone pushes on the double charge.

REST resource design: nouns, methods, and status codes

Start with the resource model, because every endpoint flows from it. The core REST idea to say out loud: model resources as nouns, and use HTTP methods as the verbs. POST /orders to create, GET /orders/{id} to read, not POST /createOrder. URLs name things; methods say what you are doing to them.

Use the methods for what they mean, because their semantics carry guarantees clients and proxies rely on:

  • GET — read, safe (no side effects) and idempotent; cacheable.
  • POST — create a new resource; not idempotent (two calls make two resources) — this is the method that needs idempotency keys.
  • PUT — replace a resource fully; idempotent (same call twice leaves the same state).
  • PATCH — partial update.
  • DELETE — remove; idempotent (deleting twice ends in the same state).

Then return status codes that mean something, so clients can act without parsing prose: 200/201 for success and creation, 400 for a bad request, 401/403 for auth, 404 for missing, 409 for a conflict, 429 for rate-limited, 5xx for server errors. A client retries a 5xx or 429; it must not blindly retry a 400. Keep the API stateless — every request carries what it needs (auth token, parameters) so any server can handle it, which is what lets you scale horizontally behind a load balancer.

"Why POST /orders and not POST /createOrder?" Because the resource is the noun and the method is the verb — modelling resources keeps the API predictable, cacheable, and consistent, and it lets the HTTP method's semantics (safe, idempotent) carry real guarantees instead of hiding behind a custom verb.

A diagram of REST resource design showing resources modelled as nouns with HTTP methods as verbs, a table of GET POST PUT PATCH and DELETE annotated as safe or idempotent, and a set of status codes mapped to outcomes like 201 created, 409 conflict, and 429 rate limited, with a note that clients retry 5xx and 429 but not 400.

Pagination, filtering, and versioning

An endpoint that returns a list has to answer: how does a client walk a million rows without asking for them all, and without breaking when the data shifts under it? This is where offset versus cursor pagination is the decision.

Offset / limit pagination (?offset=10000&limit=20) is the obvious one and the wrong default at scale. Two problems to name: the database usually has to scan and skip all the offset rows, so deep pages get slower and slower; and if rows are inserted or deleted while the user pages, items shift across page boundaries, so they see duplicates or miss rows.

Cursor (keyset) pagination fixes both. The client sends an opaque cursor — the key of the last item it saw (e.g. the last id or created_at) — and the server returns the next slice with WHERE id < cursor ORDER BY id DESC LIMIT 20. It is O(limit) regardless of depth (no skipping), and it is stable as new rows arrive at the top. The trade-off: you cannot jump to an arbitrary page number, which is fine for feeds and infinite scroll. Say the rule: cursor pagination for large or live lists; offset only for small, static datasets where page numbers matter.

Round it out with two more:

  • Filtering and sorting as query parameters (?status=open&sort=-created_at) — keep them explicit and bounded so a client cannot ask for an unindexed, unbounded scan.
  • Versioning so you can evolve without breaking clients — a version in the path (/v1/orders) or a header. The real rule is to make additive changes (new optional fields) non-breaking and reserve a version bump for genuinely breaking changes.

A diagram comparing offset pagination, which scans and skips offset rows so deep pages slow down and shifting data causes duplicates, with cursor pagination, which sends the last-seen key and reads the next slice in constant time and stays stable as new rows arrive, alongside notes on filtering as query parameters and additive versioning.

System Design
HLD · Core concept
Design and defend an API out loud

Practise on Zynter →

Idempotency and reliability: the part that actually breaks

This is where most of the follow-ups land, because it is where a plausible API corrupts data in production. The network's one promise is that requests will fail and clients will retry, so a correct API is designed for retries.

Idempotency keys. A POST is not idempotent — retrying a create makes a second resource, which for a payment means a double charge. The standard fix: the client generates a unique idempotency key (a UUID) and sends it with the request; the server records the key with the result the first time it processes it, and on any retry with the same key it returns the stored result instead of doing the work again. This turns an unsafe create into a safe one, and naming it is the single highest-value move in an API deep dive.

Rate limiting. Protect the system from abuse and overload with a rate limiter (token-bucket is the usual answer), and tell the client honestly: return 429 Too Many Requests with a Retry-After header so a well-behaved client backs off. This is both a reliability and a fairness concern.

Auth and errors. Authenticate every request (a token in the Authorization header), authorise the action, and return consistent, machine-readable error responses (a code and a message) so clients can handle failures without screen-scraping. Keep errors in the same shape across the API.

The point to state plainly: the happy path is the easy half — a strong API is judged on what it does under a retry, a flood, and a bad actor. Idempotency keys make retries safe, rate limiting keeps one client from sinking everyone, and consistent errors keep clients correct.

"The payment request times out and the client retries — how do you prevent a double charge?" The client sends an idempotency key with the POST; the server stores the result against that key on first processing and, on the retry with the same key, returns the stored result without charging again — so the operation is exactly-once from the user's point of view even though the request arrived twice.

A diagram of API reliability showing an idempotency key flow where a retried POST with the same key returns the stored result instead of charging twice, a token-bucket rate limiter returning 429 with a retry-after header, and a consistent machine-readable error response shape, labelled as the retry, flood, and bad-actor cases.

System Design
HLD · Core concept
Defend idempotency under retries out loud

Practise on Zynter →

REST, gRPC, or GraphQL — a quick placement

"Design the API" usually means REST, but naming the alternatives and when they fit reads as experience:

  • REST/JSON — the default: simple, cacheable, universally understood, great for public and resource-shaped APIs.
  • gRPC — binary, fast, strongly typed; excellent for internal service-to-service calls where latency and contracts matter more than browser friendliness.
  • GraphQL — the client asks for exactly the fields it needs in one request; useful when varied clients (mobile, web) need different shapes and you want to avoid over- and under-fetching, at the cost of caching and complexity.

Pick REST for the public resource API in most interviews, and mention gRPC for the internal hops — that one sentence shows you know the API is not one monolithic choice.

How to talk about API design in an interview

The probes from every section rhyme. Master these five and you can defend an API in any design, not just this checklist.

  • "Model this API — what do the endpoints look like?" → Resources as nouns with HTTP methods as verbs (POST /orders, GET /orders/{id}), meaningful status codes, stateless requests. (problem solving)
  • "How does a client page through a million rows?" → Cursor (keyset) pagination — send the last-seen key, read the next slice in constant time, stable under inserts; offset only for small static lists. (communication)
  • "The create request times out and the client retries — double charge?" → An idempotency key stored with the result; the retry returns the stored result instead of repeating the work. (technical execution)
  • "How do you protect the API from abuse?" → A rate limiter (token bucket) returning 429 with Retry-After, plus auth on every request. (technical execution)
  • "How do you evolve the API without breaking clients?" → Additive, non-breaking changes by default; a version bump (/v1) only for genuinely breaking changes. (problem solving)

Each maps to a debrief dimension. Reading them teaches the answers; it does not teach you to deliver them while someone interrupts with the double charge — that only comes from saying them out loud.

How to prepare: a short plan

You do not need a new topic for every design. You need the API vocabulary automatic, so when you reach the "define the API" step you move fast and leave no retry bugs.

  • Day 1: Learn REST resource modelling, the HTTP method semantics (safe/idempotent), and the status codes until you can write a clean resource API from memory and say why POST is special.
  • Day 2: Drill pagination (offset vs cursor and why), filtering, versioning, and the reliability trio — idempotency keys, rate limiting, consistent errors. These are where the follow-ups live.
  • Day 3: Define the API inside a real design (an orders service, a feed, a payment system): pick the resources, choose cursor pagination, add idempotency keys to the writes, and say where gRPC fits internally. Then do it out loud, timed, with someone pushing on the retry and the deep page.

This explainer feeds the broader Top 25 system design interview questions — the API is a step in almost every one of them, so getting it automatic pays off across the whole list.

Frequently asked questions

What makes a good API design in a system design interview?

A good API models resources as nouns and uses HTTP methods as the verbs — POST /orders to create, GET /orders/{id} to read — rather than bolting actions onto URLs. It returns meaningful status codes so clients can act (201 created, 409 conflict, 429 rate-limited), stays stateless so any server can handle any request, pages large lists with cursors rather than offsets, and makes write operations safe to retry with idempotency keys. The theme is predictability and safety under failure: the interviewer is checking whether your API survives retries, large lists, and abuse, not just whether the happy path works.

What is the difference between offset and cursor pagination?

Offset pagination (?offset=10000&limit=20) tells the database to skip a number of rows and return the next batch; it is simple but has two problems at scale — the database scans and discards all the skipped rows, so deep pages get progressively slower, and if rows are inserted or deleted while paging, items shift across page boundaries and the client sees duplicates or gaps. Cursor (keyset) pagination sends the key of the last item seen and reads the next slice directly with a WHERE key < cursor clause, which is constant time regardless of depth and stable as new rows arrive. Cursor is the right default for large or live lists; offset is acceptable only for small, static datasets where jumping to a page number matters.

What is an idempotency key and why does it matter?

An idempotency key is a unique value (usually a UUID) that a client sends with a non-idempotent request such as a POST, so the server can recognise retries of the same logical operation. The first time the server processes a request with a given key, it records the key along with the result; if the same key arrives again — because the client timed out and retried — the server returns the stored result instead of performing the operation a second time. This turns an unsafe create into an exactly-once operation from the user's perspective, which is essential for anything like a payment where a duplicate request must not cause a double charge.

Which HTTP methods are idempotent?

GET, PUT, and DELETE are idempotent: calling them repeatedly leaves the system in the same state as calling them once — GET has no side effects at all, PUT replaces a resource with the same content each time, and DELETE ends with the resource gone whether called once or many times. POST is not idempotent, because each call is meant to create a new resource, so two identical POSTs normally create two resources. That is exactly why POST is the method that needs an idempotency key to make retries safe, while GET, PUT, and DELETE are naturally retry-safe.

REST, gRPC, or GraphQL — which should I use?

REST over JSON is the default for most interview APIs: it is simple, cacheable, universally understood, and a natural fit for resource-shaped and public APIs. gRPC is a strong choice for internal service-to-service calls where you want binary efficiency, low latency, and strongly typed contracts more than browser friendliness. GraphQL lets clients request exactly the fields they need in one round trip, which helps when varied clients need different shapes and you want to avoid over- and under-fetching, at the cost of harder caching and more server complexity. A good answer picks REST for the public API and mentions gRPC for the internal hops.

How do I practise a system design interview out loud?

Reading about API design is not the same as defending an endpoint while an interviewer pushes on the double charge. On Zynter, the HLD track runs live voice rounds modelled on how real system design loops run — you talk through a design on a shared canvas, and a voice interviewer follows up one question at a time ("the create times out and retries — double charge?", "how does the client page a million rows?"), then gives you a debrief on problem solving, communication, technical execution and time management. The score is a practice signal, not a hiring decision.

Practise it on Zynter

You can list endpoints. The round is won on defending idempotency under a retry out loud.

Pick an HLD system design round, define your API on the canvas, and defend it out loud to a voice interviewer that keeps asking "the create times out and the client retries — double charge?" and "how does a client page through a million rows?" — then read the debrief. Zynter.ai is on-demand mock interviews modelled on real company loops, with 150+ rounds across 20 companies including the HLD system design track (Sep 2026).

Practise an HLD system design round →
Browse all interview tracks

Top comments (0)