A Framework for API Design Answers

That is more useful than an endpoint list, because every line is tied to a caller job and carries one design note with it.

Prioritize instead of expanding

Mark operations as:

• core: required for the primary flow;
• supporting: needed soon but not designed deeply; or
• out of scope: plausible but not required for this answer.

For example:

"Creation, retrieval, and listing are core. I'll mention update and comments for model completeness, but I'll design creation in depth. Bulk import, task templates, and full-text search are out of scope."

Scope control is part of the skill. A candidate who designs a small contract completely demonstrates better judgment than one who produces a large unfinished surface.

6. Step 4: Design One Operation in Complete Detail, 10 Minutes

This is the center of the interview, and the step most worth protecting when time runs short.

For one important operation, define the complete caller-visible contract:

1. method and path;
2. authentication or required permission;
3. important headers;
4. request fields, types, units, and validation;
5. success status and headers;
6. response body;
7. named failure cases with status codes;
8. machine-readable error body; and
9. retry or idempotency behavior.

Use task creation as the deep operation.

Request

POST /v1/projects/prj_123/tasks
Authorization: Bearer <token>
Idempotency-Key: c990fbf6-2e5c-41b8-b983-bfe08116e91a
Content-Type: application/json

{
  "title": "Prepare launch checklist",
  "description": "Cover monitoring, rollback, and support ownership.",
  "assignee_ids": ["usr_17", "usr_42"],
  "due_at": "<RFC 3339 UTC timestamp>",
  "external_id": "alert-88421"
}

Define the fields rather than leaving an interviewer to assume them:

Notice the contract decisions contained in this table. A title is not merely "a string." It has a length rule. A timestamp includes a format and timezone expectation. An omitted description is not automatically the same as null. An external identifier has a uniqueness scope.

Success response

HTTP/1.1 201 Created
Location: /v1/tasks/tsk_789

{
  "id": "tsk_789",
  "project_id": "prj_123",
  "title": "Prepare launch checklist",
  "description": "Cover monitoring, rollback, and support ownership.",
  "status": "open",
  "assignees": [
    {
      "id": "usr_17",
      "display_name": "Ari Chen"
    },
    {
      "id": "usr_42",
      "display_name": "Sam Rivera"
    }
  ],
  "due_at": "<RFC 3339 UTC timestamp>",
  "external_id": "alert-88421",
  "version": 1,
  "created_at": "<RFC 3339 UTC timestamp>",
  "updated_at": "<RFC 3339 UTC timestamp>"
}

201 Created states that a new resource exists. Location identifies it. The full representation lets a first-party client render the result without an immediate read. The version field can support later concurrency control.

Named failures

Every failure names what the caller should do about it, rather than only what went wrong.

A consistent error body might be:

{
  "error": {
    "code": "invalid_assignee",
    "message": "User usr_42 cannot be assigned to this project.",
    "field": "assignee_ids[1]",
    "request_id": "req_91a8"
  }
}

Retry behavior

If the caller times out it cannot know whether the task was created, and repeating an unprotected POST may create a second one.

The Idempotency-Key makes retry behavior explicit:

• same key and same request body: return the original result;
• same key and different body: return 400 idempotency_key_reused;
• new key: treat as a new creation attempt.

You do not need to design the idempotency storage during an API round unless somebody asks, because the caller-visible promise is the part being graded.

7. Step 5: Address the Hard Parts, 10 Minutes

The hard parts are cross-cutting decisions that affect several operations.

Common topics include:

• paging and filtering;
• retries and idempotency;
• authentication and authorization;
• rate limits;
• versioning and compatibility;
• concurrency;
• asynchronous work;
• caching;
• consistency guarantees; and
• multi-tenancy.

Do not recite all of them. Choose the ones your own requirements and your deep operation actually created.

For the task API, five relevant decisions might be:

Then explain behavior at the contract boundary.

For example:

"Task lists use an opaque next_cursor. Filters are repeated on every request, and the cursor is valid only for the same filter and sort. The response does not promise a total count because calculating an exact count may be expensive and can become stale immediately."

Or:

"An update carries the ETag from the last read in an If-Match header. If another writer changed the task, the server returns 412 Precondition Failed so the client can reload before deciding whether to retry."

Prioritize by risk

When time is short, choose the hard parts most likely to cause duplicate work, data exposure, wrong client behavior, or future incompatibility.

For a public write API, authentication, authorization, idempotency, rate limits, and versioning may dominate. For a list-heavy first-party application, paging, filtering, payload size, and caching may dominate. For long-running work, asynchronous state and completion delivery may dominate.

Name several caller-visible decisions, each connected to a requirement. "We will have rate limiting" is not enough: state who is limited, what happens at the limit, and how the caller recovers.

8. Step 6: State the Trade-offs Taken and the Options Rejected, 5 Minutes

Use the final minutes to make your judgment visible to somebody who has to score it.

Walk back through the important decisions and name what each one gave up.

For the task API:

Trade-off 1: Expanded task response versus separate assignee reads

"I included compact assignee summaries in the task response so the first-party client can render the common screen without additional reads. The cost is duplicated user data and a larger payload. I accept that for item reads but would keep large task lists more compact."

Trade-off 2: Explicit assign operation versus patching an ID array

"I chose an explicit assignment operation instead of treating assignees as a generic replaceable array. This adds an operation, but it gives assignment its own permissions, duplicate behavior, audit event, and errors."

Trade-off 3: Cursor versus offset pagination

"I chose cursor pagination because tasks can be inserted and reordered while a caller is paging. The cost is that callers cannot jump to an arbitrary page number."

Trade-off 4: Full created resource versus identifier-only response

"Creation returns the full task so the client does not need an immediate read. The cost is a larger response and more fields in the compatibility surface."

A final summary pattern

Close with:

"The design optimizes the first-party task flow and safe automation writes. I gave up some payload efficiency and surface minimalism to reduce client calls and make state transitions explicit. If the primary consumer changed to a high-volume public integration, I would revisit the expanded representations and limits."

A statement like that reminds the interviewer the design follows your stated requirements, rather than claiming to be optimal for everybody.

9. Compressing the Framework for a 30-Minute Round

For a 30-minute round, halve every step except Step 4, which still gets its full ten minutes.

The compressed steps total 27.5 minutes, leaving 2.5 minutes for interviewer questions and transitions.

What compression changes

In 30 minutes you identify one primary caller rather than every consumer, model only the resources the selected flow needs, list three to five operations rather than the full surface, discuss two or three hard parts rather than a checklist, and state two precise trade-offs. Step 4 is untouched.

What compression must not change

Never reduce Step 4 to a method and a path, because that is the evidence the round exists to collect.

The deep operation is where the interviewer sees field design, success behavior, failures, retries, and consistency working together. If you halve every step equally, you may finish on time but provide no strong evidence.

When a round is unexpectedly shortened, protect depth by cutting breadth instead.

Keep: one caller, one job, a small resource model, a few operations, one complete operation, the two hardest concerns, and two trade-offs.

Remove first: secondary callers, rare operations, speculative features, and long debates about naming.

10. Staying Oriented When the Interviewer Interrupts

Interviewers interrupt for good reasons: to test one decision, to redirect the scope, or to give you information you were missing.

Answer the question directly, then restore the structure:

"That covers the retry behavior. I was listing the core operations, so I'll finish that list and then design creation in detail."

Keep a small six-line checklist visible:

1. Consumers and jobs        [done]
2. Resources                 [done]
3. Operations                [in progress]
4. One operation in full
5. Hard parts
6. Trade-offs

That is not a script to follow mechanically. It is a reference that stops one interruption from becoming the rest of the interview.

A practical whiteboard layout

Reserve the areas before you begin, as laid out in the diagram below. The layout makes progress visible and reduces rewriting.

Key Takeaways

• Every answer in the course follows six steps in this exact order: consumers and jobs, resources, operations, one complete operation, hard parts, and trade-offs.
• The 45-minute budget is 5 + 5 + 10 + 10 + 10 + 5 minutes.
• Starting from the caller keeps the published promise stable while storage and implementation remain free to change.
• Operation names contain almost no decisions; one complete operation exposes inputs, outputs, status codes, failures, and retry behavior.
• Step 5 should cover the hard parts created by the requirements, not every API topic you remember.
• Trade-offs should name the selected option, rejected alternative, benefit, and accepted cost.
• For a 30-minute round, halve every step except Step 4, which remains ten minutes; the resulting 27.5-minute plan leaves a 2.5-minute buffer.
• When you lose time, reduce breadth before depth.

You now have the structure for a complete answer. The next lesson goes deeper into Step 1: how to identify the caller, ask requirements that settle real API decisions, and derive a contract by writing the client code you wish existed.