API Design Interview Questions and Review Checklist

You have now gone from "what is an API" to idempotency keys, OAuth and gRPC. That is a lot of pieces. In a real review or an interview, nobody asks you to recite them. They show you an endpoint list or a problem statement and ask, "What would you change?" or "How would you design this?"

This lesson gives you a way to answer. It is lesson 9 of the API design series, the last one. It leans on everything before: resources and URLs, methods and status codes, request and response design, pagination, versioning, retries, webhooks and rate limits, authentication and authorization, OpenAPI, and GraphQL and gRPC. If a checklist item looks strange, the lesson number beside it tells you where to find the full story.

Words used in this lesson

• Review checklist is a fixed list of questions you ask about every API, so you do not forget the boring but important ones.
• Smell is a sign that something is probably wrong, even if you cannot prove it yet.
• Backward compatible means old clients keep working after a change.
• Blast radius means how much damage one failure or one stolen credential can cause.
• Design question is an interview task such as "design an API for a booking system".
• Trade-off is a choice where you gain one thing and give up another. Good answers always name both sides.

Part 1: the ten-minute review checklist

Print this, or copy it into your pull request template. Each group has the lesson that explains it. A "no" to any line is not always a bug. It is a place to stop and ask "is this on purpose?".

1. Resources and URLs (lesson 0)

• URLs name things (nouns), in the plural: /orders, /orders/42. Not /getOrders.
• Names are consistent: one case style, one word per concept (not customers here and clients there).
• Nesting is shallow (at most two levels), and every nested thing can also be reached by its own id.
• Actions that are not CRUD have a clear home (a sub-resource such as POST /orders/42/cancellation, or a documented action), not a random verb in the path.
• There is a stated rule for the version (path, header or date) and it is written down.

2. Methods and status codes (lesson 1)

• GET never changes anything. It is safe to call, cache and retry.
• PUT replaces and is idempotent; PATCH changes a few fields; DELETE is idempotent; POST creates or runs an action.
• 201 with a Location header for creation. 204 for success with no body. 202 for work that finishes later.
• Errors use the right class: 400/422 for bad input, 401 for not logged in, 403 for not allowed, 404 for missing, 409 for a conflict, 429 for too many requests. Never 200 with an error inside.
• Concurrent edits are handled (ETag with If-Match, or a version field) where lost updates matter.

3. Request and response design (lesson 2)

• JSON shapes are consistent: the same field means the same thing everywhere; one naming style.
• Dates are ISO 8601 in UTC (2026-10-11T10:00:00Z). Money is in the smallest unit (cents) with a currency code, never a float.
• Responses never include secrets, password hashes, internal ids or fields the caller should not see (API3).
• Requests are validated at the edge with a schema. Unknown fields are rejected on input (stops mass assignment).
• One error format everywhere (problem details, RFC 9457), with a stable type, a human title/detail, and field-level errors for validation.
• Error messages do not leak stack traces, SQL or other users' data.

4. Lists, filtering and sorting (lesson 3)

• No endpoint returns an unbounded list. There is a default and a maximum page size.
• Cursor (keyset) pagination for big or changing data; offset only where the data is small and stable.
• Sorting is stable and has a tie-breaker (for example created_at then id).
• Filters and sorts that clients may use are listed and indexed. Unknown ones give a clear 400.
• A total count is offered only if it is cheap or clearly marked as approximate.

5. Change and compatibility (lesson 4)

• Adding a field, an endpoint or an optional parameter is treated as safe. Removing, renaming, tightening or changing meaning is treated as breaking.
• Clients are told to ignore unknown fields and unknown enum values where possible.
• A change policy exists: expand-then-contract, deprecation notices, a Sunset date, and a way to see who still uses the old thing.
• Old versions have an owner and an end date (API9: improper inventory management).

6. Reliability (lesson 5)

• Every non-idempotent POST that matters (payments, orders, emails) accepts an Idempotency-Key. The server stores key, fingerprint and result; in-progress gives 409; a different body gives 422.
• The key is claimed atomically (a database unique constraint), not with a check-then-save gap.
• Clients retry only temporary errors, with backoff and jitter, and obey Retry-After.
• Slow work returns 202 with a job URL, not a held connection.
• Webhooks: signed with HMAC over the raw body, a timestamp checked, constant-time compare, event ids for de-duplication, retries over days, secret rotation, delivery logs. The sender defends against SSRF.
• Rate limits exist per key or user, answer 429 with Retry-After, and are cost-aware on expensive endpoints. Headers are documented.

7. Security (lesson 6)

• HTTPS only. No credentials in URLs. Authorization headers are not logged.
• 401 versus 403 is used correctly, with WWW-Authenticate.
• Tokens are short-lived. JWTs are verified with a fixed algorithm and checked for iss, aud and exp. API keys are stored hashed and shown once.
• OAuth: authorization code with PKCE for user apps; exact redirect_uri match; no implicit or password grants.
• Object-level check on every id (BOLA), property-level allow-lists on input and output (mass assignment, over-exposure), function-level checks on admin routes. Default deny.
• Scopes limit the app; ownership checks limit the user. Both exist.

8. Documentation and contract (lesson 7)

• An OpenAPI file (or equivalent) is the source of truth, validated and linted in CI.
• Every operation has operationId, summary, examples, and its error responses.
• A contract test runs against the real server and fails the build when responses drift from the file.
• A breaking-change diff runs between the main branch and each pull request.
• Idempotency, rate limit, pagination and webhook behaviour is documented in words, not only in the schema.

9. Style fit (lesson 8)

• The style (REST, GraphQL, gRPC) was chosen for a stated reason.
• If GraphQL: batching for N+1, depth and cost limits, field-level auth, introspection off for private APIs.
• If gRPC: field numbers are never reused, deadlines are set on every call, TLS is on, and browser access is solved.

10. Operations (touched in lessons 5 and 8, deeper in the Backend series)

• Every request has a request id in logs and in an error body, so support can find it.
• Logs are structured and do not hold secrets. Latency and error rate are measured per endpoint.
• There are timeouts on every outgoing call, and a plan for what the API does when a dependency is down.

See Backend lesson 5 for logging and request ids.

The OWASP API Top 10 as a final pass

The 2023 list is a good last pass because it is what attackers try first. Read each name and ask "where could this be true for us?": API1 broken object level authorization, API2 broken authentication, API3 broken object property level authorization, API4 unrestricted resource consumption, API5 broken function level authorization, API6 unrestricted access to sensitive business flows, API7 server side request forgery, API8 security misconfiguration, API9 improper inventory management, API10 unsafe consumption of APIs. (I read the summary table of this list in the OWASP repository. As with all Top 10 lists, say which year's edition you mean.)

Part 2: make part of the checklist automatic

A checklist that lives in someone's head is skipped on busy days. The parts that a machine can check should be checked by a machine. Here is a short script that reads an OpenAPI file (through the parser from lesson 7) and applies eight rules from the list above. It is deliberately small, so you can read it in two minutes and change it for your own team.

// review.mjsimport SwaggerParser from "@apidevtools/swagger-parser";const api = await SwaggerParser.dereference(process.argv[2]);const problems = [];const add = (where, msg) => problems.push(`${where}: ${msg}`);const METHODS = ["get", "put", "post", "patch", "delete"];if (!api.servers?.length) add("root", "no servers listed");if (!api.security && !Object.values(api.paths).some(p => METHODS.some(m => p[m]?.security)))  add("root", "no security declared anywhere");for (const [path, item] of Object.entries(api.paths)) {  // resource naming: lower-case, no verbs in the path  for (const s of path.split("/").filter(s => s && !s.startsWith("{"))) {    if (/[A-Z_]/.test(s)) add(path, `segment "${s}" should be lower-case kebab-case`);    if (/^(get|create|delete|update|do|run)/i.test(s)) add(path, `segment "${s}" looks like a verb`);  }  for (const m of METHODS) {    const op = item[m]; if (!op) continue;    const where = `${m.toUpperCase()} ${path}`;    const codes = Object.keys(op.responses ?? {});    if (!op.operationId) add(where, "missing operationId");    if (!op.summary) add(where, "missing summary");    if (!codes.some(c => c.startsWith("4"))) add(where, "no 4xx response documented");    const secured = (op.security ?? api.security ?? []).length > 0;    if (secured && !codes.includes("401")) add(where, "secured but no 401 documented");    if (m === "post") {      const hasKey = (op.parameters ?? []).some(p => p.in === "header" && p.name.toLowerCase() === "idempotency-key");      if (!hasKey) add(where, "POST without Idempotency-Key");      if (!codes.includes("429")) add(where, "POST without 429 documented");      if (codes.includes("201") && !op.responses["201"].headers?.Location) add(where, "201 without Location header");    }    if (m === "get" && !path.endsWith("}")) {      const names = (op.parameters ?? []).map(p => p.name);      if (!names.includes("limit") && !names.includes("page_size")) add(where, "collection GET without a page-size parameter");    }    for (const [code, r] of Object.entries(op.responses ?? {}))      if (code.startsWith("4") || code.startsWith("5"))        if (!Object.keys(r.content ?? {}).includes("application/problem+json"))          add(`${where} ${code}`, "error is not application/problem+json");  }}console.log(`${process.argv[2]}: ${problems.length} finding(s)`);for (const p of problems) console.log("  - " + p);

I ran it on two files. The first is the orders API file from lesson 7. The second, bad.yaml, is a small shop API written the way many first drafts look:

openapi: 3.1.0info: { title: Shop, version: "1" }paths:  /getOrders:    get:      responses:        "200": { description: ok }  /Orders_List:    post:      summary: make order      responses:        "201": { description: created }        "500":          description: boom          content:            application/json:              schema: { type: object }

Real output:

../l7/openapi.yaml: 0 finding(s)bad.yaml: 15 finding(s)  - root: no servers listed  - root: no security declared anywhere  - /getOrders: segment "getOrders" should be lower-case kebab-case  - /getOrders: segment "getOrders" looks like a verb  - GET /getOrders: missing operationId  - GET /getOrders: missing summary  - GET /getOrders: no 4xx response documented  - GET /getOrders: collection GET without a page-size parameter  - /Orders_List: segment "Orders_List" should be lower-case kebab-case  - POST /Orders_List: missing operationId  - POST /Orders_List: no 4xx response documented  - POST /Orders_List: POST without Idempotency-Key  - POST /Orders_List: POST without 429 documented  - POST /Orders_List: 201 without Location header  - POST /Orders_List 500: error is not application/problem+json

An honest note: the good file passes cleanly because I wrote it to follow these rules in lesson 7, so a zero is not proof that it is perfect. And the script cannot judge what it cannot see. It does not know if /Orders_List should be /orders, or if the 500 should exist at all. It catches the mechanical slips. Humans must still judge the design. Use the script to free review time for the questions only a person can answer, such as "is this the right resource model?" and "who may call this?".

Part 3: a worked review of a bad API

Here is a design as it might appear in a pull request for a small booking service. Read it first and write down what you would change before you read my list.

POST   /createBooking          body: {userId, roomId, start, end, price: 49.99}GET    /getBookings?userId=7   returns every booking (could be 100000) as an arrayPOST   /bookings/cancel        body: {id}GET    /deleteBooking/12       (deletes it)PUT    /booking/12             body: {status: "paid"}     (only status sent)Every response: 200 OK. Errors look like {"success": false, "msg": "Something went wrong"}Auth: the client sends header X-User-Id: 7Dates: "10/11/26 3pm"

My review, in order of the checklist:

Count how many of the fifteen are about style (1, 2, 8) and how many are about correctness or safety (3, 4, 6, 7, 9, 12, 13, 14). The safety ones are the ones to say first in an interview, because they cost real money.

Part 4: a design problem, step by step

Interviewers love: "Design the API for a booking system" (or a library, a to-do app, a ride-hailing service). They are not hunting for the perfect answer. They watch how you think. Use this order. It is the series in seven steps.

Step 1: clarify (two minutes). Ask who calls the API (a mobile app, partners, internal services), what the main actions are, how big it is (users, requests per second), and what must never go wrong (double booking, double charge). Write down two or three answers. This also shows you think about the problem before the solution.

Step 2: find the resources. Nouns: rooms, bookings, customers, payments. Draw how they relate: a booking belongs to one customer and one room and has one payment.

Step 3: list the operations. For each resource: list, create, read, change, delete, and the special actions.

GET    /rooms?city=...&available_from=...&available_to=...&limit=20&cursor=...GET    /rooms/{roomId}POST   /bookings                         (Idempotency-Key required)   -> 201 + LocationGET    /bookings?status=confirmed&limit=20&cursor=...                   (only my own)GET    /bookings/{bookingId}PATCH  /bookings/{bookingId}             (change dates, If-Match with ETag)POST   /bookings/{bookingId}/cancellation -> 201 or 200POST   /bookings/{bookingId}/payments    (Idempotency-Key required)

Step 4: shapes and errors. Show one booking JSON: id, status (enum: pending, confirmed, cancelled), room_id, starts_at, ends_at (UTC), total_cents, currency. State the error format (problem details) and name the important error cases: 409 room not available, 422 end before start, 404 not found (also for someone else's booking), 429.

Step 5: the hard parts. This is where you win the interview. Say: (a) retries and double booking: idempotency key plus a database constraint on room and time range; (b) payment: the payment provider calls me back, so I need a webhook receiver that verifies signatures and de-duplicates by event id; (c) slow things such as sending confirmation emails happen in the background; (d) lists are paginated by cursor; (e) rate limits per user and per IP, stricter on POST /bookings.

Step 6: security. Say who calls and how: users log in through OAuth, and the API checks scope and then ownership on every booking id. Staff have a role and different scopes. Input is validated with a schema. Responses include only fields the caller may see.

Step 7: evolution and contract. Say you would write the OpenAPI file first, run contract tests in CI, add new fields without a version bump, and use a Sunset header when something must go.

Finish with the trade-off you made and what you would watch in production: "I chose cursor pagination, so we lose jump-to-page-37. I'd watch the p95 latency of the availability search, because that is the heaviest query."

This answer fits in ten minutes. If you have fifteen, add the data model (the overlap constraint), caching of room data, and the notification flow.

Part 5: how to talk in an API interview

A few habits that separate strong answers from weak ones:

1. Say the trade-off. "Offset pagination is simple, but it gets slower with big offsets and can skip rows when data changes. Cursor pagination fixes both, but you cannot jump to a page." Two sides every time.
2. Start with the failure, not the happy path. "What happens if the client times out after we charged the card?" is the question that shows experience.
3. Name the status code. Do not say "an error". Say "409 Conflict because the room is already taken".
4. Use a number or a real result when you have one. From this series: three parallel requests created three charges until the key was claimed atomically; a token bucket allowed 5 requests where a fixed window allowed 10 at a boundary; a naive GraphQL query did 11 database calls and a batched one did 2; a protobuf message was 16 bytes against 48 in JSON. A small true example beats a long abstract one.
5. Admit what you have not used. "I have not run gRPC in production. I have built a small service and I know the status codes and the browser limits" is better than a bluff.
6. Connect layers. Rate limits protect the service; authorization protects data; idempotency protects money. Say which one you are using and why.

Try it

1. Take an API you built or use at work. Run the checklist. Find three items that fail. For each, write one sentence: "Fix now", "Fix next quarter" or "Accept, because...".
2. Run the review script from Part 2 on an OpenAPI file you own, or write a small one for two endpoints. Which finding surprised you?
3. Redesign the bad booking API from Part 3 into the final list of endpoints. Check that every URL is a noun, every POST that matters has an idempotency key, and no URL contains userId.
4. Practise the seven-step design out loud for a library system (books, members, loans) in ten minutes. Record yourself. Did you mention a failure case before the happy path ended?
5. Write the three headers a 429 response should carry or may carry (hint: lesson 5). Then write the two headers a 201 should carry.

Answers

1. There is no single answer. If many fail on one theme (for example no idempotency, no pagination, no ownership checks), start with the theme that can lose money or data. Security and reliability items usually come before style items.
2. Common surprises: missing operationIds, no 4xx response documented on POST, and collection endpoints without a page-size parameter. These are the cheap, mechanical ones.
3. A reasonable list: GET /bookings, POST /bookings, GET /bookings/{id}, PATCH /bookings/{id}, POST /bookings/{id}/cancellation. The user comes from the token. POST /bookings takes Idempotency-Key and returns 201 with Location.
4. Resources: books, members, loans. Hard parts: one copy cannot be loaned twice (unique constraint on active loan per copy), overdue notices (background jobs, webhooks or email), fines (money in cents). Failure case: the librarian's tablet loses connection after scanning, so the check-out is retried and needs an idempotency key.
5. 429 Too Many Requests with Retry-After, and optionally RateLimit and RateLimit-Policy (from the IETF draft) so clients can slow down early. A 201 should carry Location pointing to the new resource, and Content-Type: application/json (and an ETag if you use optimistic concurrency).

Interview questions

These cover the whole series. Answers are first-person and short enough to say aloud. Where a question points back to a lesson, the answer is the summary of it.

Key takeaways

• Review in the same order every time: names, methods, shapes, errors, lists, change, retries, security, docs, style fit, operations.
• Say the money-and-data risks first: no authorization on objects, no idempotency, unbounded lists, wrong status codes.
• A checklist helps most when machines do the mechanical parts (lint, contract tests, diff) and people judge the design.
• The strongest interview answers name the failure case, the status code and the trade-off, and use one small real number or example.
• Protect the business rule at the lowest layer that can enforce it (a database constraint), not only at the HTTP edge.
• REST, GraphQL and gRPC are tools. The decisions in this series (names, errors, retries, auth, docs, change) apply to all of them.

What's next

This is the end of the API design series. To keep going:

• Put these ideas into a working service with the Backend in Depth series: folders, validation, error handling, logging, auth and testing.
• Study the attack side in the Security for Developers series, especially access control (lesson 4) and APIs and servers (lesson 7).
• Practise out loud with Full-Stack lesson 30 (tRPC, REST and OpenAPI) and Full-Stack lesson 22 (auth libraries, OAuth and OIDC).

Your homework: pick one real API, run the checklist, write down the three most important fixes, and explain them to a friend in under two minutes. If you can do that clearly, you are ready for the interview.