In this article
Starting the design
Where do you start when asked to design an API?
Start with who calls it and what they need to do, before any endpoint. Ask about the consumers, the main tasks, expected volume and how long old clients will live, then list the nouns, the resources, and only then the operations on them. Say the assumptions aloud, because the interviewer will change them. A design that begins with URLs has skipped the reasoning that makes URLs good.
Why it is asked: it separates designers from people who recite endpoints. Read the full explanation: the system design hub.
How do you turn requirements into resources and names?
A resource is a named thing the API exposes, such as an order or a customer. Google's API Improvement Proposals (AIP) say the building blocks of an API are individually named resources, nouns, and that a small set of standard methods, Get, List, Create, Update and Delete, covers most operations (AIP-121, 2019). Model the nouns first, name them consistently, and add a custom verb only when none of the five fits.
Why it is asked: naming shows whether your model is coherent. Read the full explanation: representational state transfer (REST) API interview questions.
REST, GraphQL or gRPC: how do you choose?
Choose by who calls and what they need. REST (representational state transfer) maps resources to the Hypertext Transfer Protocol (HTTP) and suits public, cacheable interfaces. GraphQL is a query language for your API with a server-side runtime and a type system you define (GraphQL Foundation, as of October 2026), so it fits clients that need to pick fields. gRPC defines services in proto files with protocol buffers, a compact binary message format (gRPC, 2024), so it fits internal service-to-service calls.
Why it is asked: it checks that you choose for a reason. Read the full explanation: gRPC introduction.
How do you describe the API so consumers can use it without your code?
Write a machine-readable description. The OpenAPI Specification defines a standard, programming-language-agnostic interface description for HTTP APIs, so people and tools can understand what a service does without its source code or network traffic (OpenAPI 3.2.1, September 2026). From one description you can generate reference documentation, client libraries and contract tests. Keep it in the repository and review changes to it like code.
Why it is asked: it tests whether you think of the contract as a product. Read the full explanation: OpenAPI Specification.
Requests, errors and pagination
Which HTTP method does each operation get?
Use GET to read, POST to create or trigger, PUT to replace, PATCH to change part, and DELETE to remove. The properties matter more than the names. The Request for Comments (RFC) 9110 calls a method safe if its semantics are essentially read-only, and idempotent, meaning repeating it has the same intended effect as sending it once, and lists PUT, DELETE and the safe methods as idempotent (RFC 9110, June 2022). So GET and HEAD are safe and idempotent, PUT and DELETE are idempotent but not safe, and POST is neither.
Why it is asked: retry behaviour depends on it. Read the full explanation: REST API interview questions.
Text description of the diagram
- GET and HEAD are safe and idempotent.
- PUT and DELETE are idempotent but not safe, and POST is neither.
How should the API return errors?
Return the right status code, such as a 2xx (success) code on success and a 4xx code for the caller's mistakes, and a machine-readable body. RFC 9457 defines a problem details format, served as application/problem+json, with a type given as a uniform resource identifier (URI), a status, a title, a detail and an instance, so clients need no new error format per API (RFC 9457, July 2023). Use 409 for a conflict with current state, which RFC 9110 says the user might be able to resolve, and 422 for content the server understood but cannot process.
Why it is asked: errors are most of what clients see. Read the full explanation: RFC 9457.
How do you paginate a large collection?
Return a page and an opaque token for the next one. Google's pagination rules say the page size must be optional, values above the maximum are reduced, and the next-page token must be empty at the end of the collection; tokens must be opaque and URL-safe, and base-64 encoding a readable token is not enough (AIP-158, 2019). Order results uniquely, or pages will repeat rows.
Why it is asked: every list endpoint needs it. Read the full explanation: AIP-158.
Why does deep offset pagination fail, and what replaces it?
The database must still compute the skipped rows: PostgreSQL's documentation says rows skipped by the offset clause still have to be computed inside the server, so a large offset might be inefficient (PostgreSQL 18). It also drifts when rows are inserted. Keyset pagination, also called cursor pagination, filters on the last key seen, such as id greater than the last id, so the cost stays at the page size.1
Why it is asked: it separates textbook answers from production ones. Read the full explanation: the arithmetic below.
Knowing it is half the job. Saying it is the other half.
Interview Clozo is an AI interview copilot for real interview rounds: it hears the question and puts a strong answer on your screen, and you say it in your own words. See the features or how it works.
Start Free Trial →Reliability
How do you stop two clients overwriting each other's update?
Use optimistic concurrency with entity tags. The server returns an ETag with the resource, the client sends it back in an If-Match header on the update, and the server applies the change only if the tag still matches. RFC 9110 says a failed condition returns 412, Precondition Failed, which prevents the method being applied if the target is in an unexpected state (RFC 9110).
Why it is asked: lost updates are a classic hidden bug. Read the full explanation: backend interview questions.
How do you make a payment request safe to retry?
Require an idempotency key. An idempotency key is a unique value the client generates for one logical request, so the server can recognise a retry. For its v1 API, Stripe saves the status code and body of the first request made with a key and returns the saved response on retries, accepts keys up to 255 characters, and may prune them after 24 hours (Stripe API reference, as of October 2026).
Why it is asked: a duplicate charge is a real incident. Read the full explanation: design a payment system.
How do you rate limit callers, and what do you tell them?
Limit per caller, and answer with 429. RFC 6585 defines 429 Too Many Requests for a user who has sent too many requests in a given time, and says the response may include a Retry-After header saying how long to wait (RFC 6585, April 2012). Retry-After carries either a date or a number of seconds (RFC 9110). Document the limits.
Why it is asked: it tests protecting the service and helping the client. Read the full explanation: design a rate limiter.
How should clients retry without taking the service down?
Retry with exponential backoff and jitter, at one layer only. Backoff makes the client wait between tries, and jitter adds randomness so retries do not collide. If every layer of a call chain retries independently, load multiplies: with three tries per layer, a five-deep call chain sends 243 calls to the database for one request, the 243x that Amazon Web Services (AWS) describes (Builder Center, December 2019).1 Pick one layer to own retries and cap them.
Why it is asked: retry storms cause outages. Read the full explanation: AWS Builder Center article.
How do you handle an operation that takes a minute?
Do not hold the connection. Return 202 Accepted, which RFC 9110 says means the request has been accepted for processing but not completed, with a representation that describes the current status and points to a status monitor (RFC 9110). Google's guide returns an operation object that the caller polls, with a rule of thumb of 10 seconds as the threshold (AIP-151, 2019).
Why it is asked: it tests asynchronous design. Read the full explanation: AIP-151.
Should the API use webhooks or polling for events?
Use webhooks when clients need to react to events and polling as the fallback. A webhook is an HTTP call your server makes to a client's URL when an event occurs. Stripe's documentation says to return a 2xx quickly, to verify the signature, to expect duplicates and to track event IDs, and says events do not arrive in a fixed order; it retries for up to three days in live mode with exponential backoff (Stripe webhooks, as of October 2026).
Why it is asked: it shows you design for the receiver's failures. Read the full explanation: webhooks.
Change over time
What counts as a breaking change?
A breaking change is any change that can make an existing, correct client fail. Google's compatibility rules allow adding components in the same major version but not adding required request fields, and forbid removing or renaming components, changing field types even when wire-compatible (the bytes on the network would still parse), or changing resource names (AIP-180, 2019). Treat a changed default value as breaking too.
Why it is asked: it checks that you think about clients you cannot see. Read the full explanation: AIP-180.
How do you version an API?
Prefer evolving compatibly, and version only for breaks. Semantic Versioning 2.0.0 says to increase the major version for incompatible API changes, the minor version for backward-compatible functionality and the patch version for backward-compatible fixes (semver.org, as of October 2026). Expose the major version in the path or header, support the old one for a stated period, and keep each version's behaviour frozen.
Why it is asked: versioning is where designs meet reality. Read the full explanation: Semantic Versioning.
How do you retire an endpoint?
Announce, signal, then switch off. RFC 8594 defines the Sunset response header, which says a URI is likely to become unresponsive at a specified point in the future (RFC 8594, May 2019). RFC 9745 adds a Deprecation header field for announcing that a resource is or will be deprecated (RFC 9745, March 2025). Semantic Versioning requires the minor version to rise when functionality is marked deprecated. Publish the date, email active callers and watch traffic fall before you remove anything.
Why it is asked: deprecation is a people problem. Read the full explanation: RFC 8594.
Security and limits
How do you make sure a caller can access only their own objects?
Check authorisation on every object, not only at login. The Open Worldwide Application Security Project (OWASP) API Security Top 10 puts broken object-level authorization first, and advises an authorization mechanism based on user policies, used in every function that takes an identifier from the client to reach a record, plus random, unpredictable identifiers (OWASP, 2023, broken object-level authorization).
Why it is asked: swapping an identifier is the easiest attack. Read the full explanation: OWASP on object-level authorization.
Which API-specific risks should you be able to name?
Name the list, then pick the ones your design touches. The 2023 OWASP list is broken object-level authorization, broken authentication, broken object property level authorization, unrestricted resource consumption, broken function level authorization, unrestricted access to sensitive business flows, server-side request forgery, security misconfiguration, improper inventory management and unsafe consumption of APIs (OWASP, 2023).
Why it is asked: it shows security is in your design vocabulary. Read the full explanation: OWASP API Security Top 10.
How do you cap what one caller can consume?
Limit every dimension a request can inflate. OWASP's advice on unrestricted resource consumption is to set limits on memory and processor time, validate the page size server-side, define a maximum size for incoming parameters and payloads, and rate limit by caller (OWASP, 2023, unrestricted resource consumption). A maximum page size also protects the pagination you designed earlier.
Why it is asked: unbounded requests are an outage waiting. Read the full explanation: OWASP on resource consumption.
The arithmetic behind the answers
Every number below comes from the saved script. The page size of 20, the three attempts per layer and the loss rate are illustrative inputs, not measurements of any service.
| Case | Result |
|---|---|
| Rows examined for page 1 with offset, page size 20 | 20 |
| Rows examined for page 100, page 1,000 and page 10,000 with offset | 2,000, then 20,000, then 200,000 |
| Rows read for any page with keyset pagination | 20 |
| Row shown twice after an insert at the start, offset pages of 3 | 1 (id 3); with keyset, 0 |
| Calls at the bottom from one failing request, 3 attempts per layer, 1 to 5 layers | 3, 9, 27, 81, 243 |
| Duplicate charges in 1,000,000 simulated payments, 0.5% responses lost, no key | 4,985 |
| Same simulation with an idempotency key | 0 |
For pagination, offset pages of 20 cost (page minus one) times 20 plus 20 rows, while keyset pages cost 20 rows with an index on the key; on a 100,000-row table in SQLite the offset and keyset queries returned identical pages for pages 1, 100 and 1,000.1 The multiplication in the retry row is three attempts per layer, so three to the power of the number of layers, matching the 243 times AWS describes for five layers. The payment row is a simulation with seed 0: 4,985 responses were lost after the charge had been applied, and without a key each retry charged again.
Text description of the diagram
- Offset pagination examines 20 rows at page 1 and 200,000 rows at page 10,000.
- Keyset pagination reads 20 rows at every page.
Offset pagination examines 20 rows at page 1 and 200,000 rows at page 10,000, and keyset pagination reads 20 rows at every page.1
Step-by-step description
- Three attempts reach the bottom.
- Each attempt is retried again: 9.
- 27 calls.
- 81 calls.
- 243 calls from one request.
- With 3 attempts per layer, one failing request makes 3 calls through one layer and 9 through two.
- It makes 27 calls through three layers, 81 through four and 243 through five.
With 3 attempts per layer, one failing request makes 3 calls through one layer and 9 through two. It makes 27 calls through three layers, 81 through four and 243 through five.1
Follow-up questions
How should I prepare for an API design interview?
Pick two products you know and sketch their APIs from the resources outward, then add pagination, idempotency, errors and a versioning plan to each. Say the trade-offs aloud. The wider format of such rounds is in the system design hub, and the object-level version is in low-level design questions.
How is an API design round different from a system design round?
An API design round stops at the contract between caller and service: resources, requests, errors and change. A system design round goes behind it to storage, scaling and failure. Expect the first to turn into the second, as in the interview loop overview.
Should the default API style be REST?
For a public, general-purpose interface, REST over HTTP is the usual default, because tools, caches and developers all understand it. Move to GraphQL or gRPC when a specific need, such as client-chosen fields or internal service calls, justifies the cost.
- Start from callers and resources, not from URLs.
- Retry only idempotent requests, and give every create an idempotency key.
- Paginate with opaque cursors, and cap page size and request size.
- Never break existing clients inside a version; announce and sunset what you retire.
- Authorise every object, not only the caller.
Sources
- RFC 9110: HTTP Semantics — IETF (Fielding, Nottingham, Reschke), 1 Jun 2022
- RFC 9457: Problem Details for HTTP APIs — IETF, 1 Jul 2023
- RFC 6585: Additional HTTP Status Codes — IETF (Nottingham, Fielding), 1 Apr 2012
- RFC 8594: The Sunset HTTP Header Field — IETF, 1 May 2019
- AIP-121: Resource-oriented design — Google API Improvement Proposals, 26 Jan 2019
- AIP-151: Long-running operations — Google API Improvement Proposals, 25 Jul 2019
- AIP-158: Pagination — Google API Improvement Proposals, 18 Feb 2019
- AIP-180: Backwards compatibility — Google API Improvement Proposals, 23 Jul 2019
- Idempotent requests (Stripe API reference) — Stripe (date = read date), 24 Oct 2026
- Receive Stripe events in your webhook endpoint — Stripe (date = read date), 24 Oct 2026
- OWASP API Security Top 10 2023 — OWASP, 5 Jun 2023
- OpenAPI Specification, version 3.2.1 — OpenAPI Initiative, 10 Sep 2026
- GraphQL: Introduction to GraphQL — GraphQL Foundation (date = read date), 24 Oct 2026
- Introduction to gRPC — gRPC Authors (page last modified 12 November 2024), 12 Nov 2024
- API1:2023 Broken Object Level Authorization — OWASP, 5 Jun 2023
- API4:2023 Unrestricted Resource Consumption — OWASP, 5 Jun 2023
- Semantic Versioning 2.0.0 — semver.org (date = read date), 24 Oct 2026
- LIMIT and OFFSET (PostgreSQL 18 documentation) — PostgreSQL Global Development Group (date = read date), 24 Oct 2026
- RFC 9745: The Deprecation HTTP Response Header Field — IETF, 1 Mar 2025
- Timeouts, retries, and backoff with jitter — AWS Builder Center, 5 Dec 2019
