What Interviewers Actually Grade

An interviewer cannot grade an API that you never describe out loud.

They can grade only the evidence you place in the conversation: the questions you ask, the model you draw, the operation you specify, the failures you name, and the alternatives you compare.

This explains a frustrating result. A candidate with the experience to design a good API at work can still be rated average, because the reasoning was never said aloud. Another can choose a different design and rate higher, because every decision and cost was visible.

The scorecard is not mainly about remembering HTTP vocabulary. It is about five signals:

1. You start from the caller and the job.
2. You create a consistent model.
3. You design failures as part of the contract.
4. You plan for change.
5. You state trade-offs aloud.

Companies use different labels, but these five answer the questions every real API owner must answer.

Each signal below is presented as a weak answer against a strong one. Section 6 ranks them by how much they move a rating.

1. Signal One: Start from the Caller and the Job

This signal appears before you draw a resource or name an operation. Who will call this API, and what are they trying to finish?

A mobile application, a partner integration, an internal service, and a script may share one underlying service and still need different contracts. The mobile client wants one compact response for a weak network. The partner wants stable resources, explicit limits, and long deprecations. The internal service wants throughput, idempotent writes, and machine-readable failures.

What a weak answer sounds like

"We have users, orders, and order items in the database, so I'll create endpoints for those tables."

The storage model was chosen before the caller's job. "I'll use REST. We need GET, POST, PUT, and DELETE" is the same failure: neither says what the caller is trying to accomplish.

What a strong answer sounds like

"Who are the main consumers? Is this API used by our checkout application, external merchants, or both?"

Then:

"For the first-party checkout client, the two important jobs are creating an order and showing its current state. I'll design around those jobs first."

The strong answer does not gather every possible requirement. It identifies enough context to make the next decision correctly.

2. Signal Two: Create a Consistent Model

Consistency makes an API learnable. After seeing two operations, a caller should predict the third. If one collection returns next_cursor, every cursor-paginated collection uses that field. If errors carry error.code, the next operation does not return a free-form reason.

The rule covers naming, URL structure, field casing, identifier shape, units, collection envelopes, pagination, error bodies, filtering, and sorting. The goal is not visual neatness. It is prediction.

What a weak answer sounds like

"To get a user, call GET /user?id=123. To get a project, call POST /projects/get with projectId. To get a task, call GET /tasks/123."

Each may work, but the caller learns a new pattern every time. Are reads GET or POST? Are identifiers in the path, query, or body? Every inconsistency becomes documentation to read and code to special-case.

What a strong answer sounds like

"I'll use plural collection paths and place the resource identifier in the path: GET /users/{user_id}, GET /projects/{project_id}, and GET /tasks/{task_id}. Collection operations will use the same cursor envelope and error shape."

The important part is not that plural nouns are correct. It is that the contract has a rule and the rule still applies to the next operation.

The prediction test: if the interviewer saw two examples, could they guess the shape of the third? If not, either the model is inconsistent or an exception needs explaining.

3. Signal Three: Design Failures, Not Just Successes

A contract is incomplete until the caller knows what can go wrong, because different failures require different actions:

• malformed input should be fixed before retrying;
• missing authentication requires new credentials;
• insufficient permission may require a different user or scope;
• a conflict may require fresh state;
• a rate limit may require waiting; and
• a temporary server failure may be safe to retry.

If every failure becomes 500 Internal Server Error, the caller cannot respond correctly.

What a weak answer sounds like

"On success, I'll return the object. Otherwise, I'll return an error."

The word "error" leaves every decision unmade. "400 for anything the client did wrong and 500 for everything else" is better, but a program still cannot separate a missing field from a conflict, an expired credential, or a rate limit.

What a strong answer sounds like

"Creation has four caller-visible failures: 400 when the request cannot be parsed or a required field is missing, 404 when the referenced project does not exist, 409 when the requested unique key already belongs to another resource, and 429 when the caller exceeds its write limit. Every failure uses the same machine-readable body."

{
  "error": {
    "code": "duplicate_external_id",
    "message": "A task with this external ID already exists.",
    "field": "external_id",
    "request_id": "req_7f91"
  }
}

The message helps a developer, the stable code lets software branch, the field says what to fix, and the request_id lets support staff find that exact call in the logs. The wording of the message never becomes part of the contract.

Status codes are behavioral decisions. They influence what clients, SDKs, gateways, monitors, and retry systems do. A validation failure that returns 500 makes clients retry a request that can never succeed. A throttling response that returns 400 with no retry guidance makes a client fail permanently when it should have waited.

4. Signal Four: Plan for Change

The API you design in the interview is version one, even if the question does not say so. The interviewer wants evidence that version two can exist without breaking version one's callers. Be ready to explain three changes.

Adding a field. Usually compatible if callers ignore what they do not recognize, but an added field is not automatically safe: a field can increase payload size, expose sensitive data, or change caching. State the expectation that clients ignore unknown fields. In requests, an optional field with a default is far easier than a required one, which breaks every existing caller.

Adding an operation. Normally additive, since existing callers do not invoke it, provided it follows the existing naming, error, and pagination patterns. The harder question is whether it should be a new operation or a flag on an existing one. Many flags create combinations nobody can reason about.

Removing something. This follows from the permanence rule in Lesson 2: mark it deprecated, name the alternative, give notice, measure usage, and support both during the migration window. Some callers will not migrate on time. Removal is a coordination process, not only a code change.

What a weak answer sounds like

"If the API changes, we'll create /v2."

Versioning may be necessary, but this postpones the problem. What changed? Why was an additive change impossible? Does every field addition need a new version?

"This is an internal API, so we can change it whenever we want" is also weak. Internal callers are easier to find, but other teams deploy on their own schedules, and old jobs stay in production.

What a strong answer sounds like

"I'll make response evolution additive: clients ignore unknown fields, and new request fields are optional with documented defaults. If we must replace the state model with incompatible semantics, I would introduce the new representation alongside the old one, deprecate the old field, publish the translation, measure usage, and remove it only after the migration window."

5. Signal Five: State Trade-offs Aloud

API design questions rarely have one correct answer. Should creation return the full resource or only its identifier? Should long-running work poll or use a webhook? Your choice does not need to match the interviewer's. It needs to be visibly deliberate: name the option, the rejected alternative, the benefit, and the cost.

What a weak answer sounds like

"I'll use cursor pagination."

It may be the right choice, but the interviewer cannot tell whether the candidate understands it. "Cursor pagination is better" is worse: better for what?

What a strong answer sounds like

"I'll use cursor pagination instead of page numbers because records are inserted frequently and callers need stable continuation without skipped or duplicated positions. The cost is that callers cannot jump directly to page 20, and the cursor must remain opaque."

A trade-off does not require a five-minute debate. One precise sentence exposes the reasoning, and this pattern gives you the sentence:

"I chose A instead of B because this caller needs benefit. The cost is cost, which I accept because requirement."

6. Which Signals Affect the Rating Most?

There is no universal point system. Companies, roles, and interviewers use different rubrics. Still, the signals affect the conversation in different ways.

Three moments often have the greatest immediate effect on the rating:

1. Your opening: do you begin with the caller and job?
2. Your complete operation: do you design both success and failure?
3. Your decision statements: do you compare alternatives and name costs?

Consistency is judged across the entire answer rather than in one moment. Evolution planning often separates a competent mid-level answer from a senior-level one. None of the five can be ignored, but protect these three when time is short.