API design interview preparation: contracts, versioning, and errors

Start from the consumer, not the database

Good API design starts with who calls it and what they need to accomplish. Before naming endpoints, ask: what operations does the consumer perform, in what order, and what do they need back? A design that mirrors your internal tables instead of the consumer's tasks leaks implementation detail and ages badly.

Microsoft's REST API guidelines emphasise consistency and developer experience: predictable naming, structured errors, and behaviour consumers can rely on without reading your source. That is the evaluated skill in an interview. Reciting endpoint naming conventions without the consumer reasoning reads as memorisation.

Reference: Microsoft: REST API guidelines

Model resources and their relationships clearly

Name the resources your API exposes and the relationships between them. Orders belong to customers; a payment belongs to an order. Interviewers probe how you handle the awkward cases: resources that exist across boundaries, operations that do not fit CRUD cleanly, and nested versus flat structures.

When a resource does not map to a verb, discuss the options honestly: a sub-resource, a separate action endpoint, or a job resource that represents the operation itself. The evaluated behaviour is recognising that the awkward cases exist and choosing deliberately, not forcing every operation into a CRUD shape.

Design request and response shapes deliberately

For each operation, say what goes in, what comes back, and what is optional. Prefer explicit fields over bags of properties, and keep response shapes stable enough that consumers can program against them. Returning different shapes depending on internal conditions is a common design smell interviewers probe.

Discuss errors as part of the contract, not an afterthought. A consistent error format with a machine-readable code and a human-readable message lets consumers handle failures programmatically. 'Returns a 400' is not a designed error contract; 'returns a consistent error body with a code consumers can switch on' is.

• Resources: the nouns the API exposes and their relationships
• Requests: required versus optional input and validation
• Responses: stable shapes consumers can program against
• Errors: consistent, machine-readable, and documented

Get idempotency and pagination right

Idempotency questions appear constantly in API interviews because they test whether you understand what retries do to unsafe operations. Explain which operations are naturally safe to retry, which need an idempotency key or a dedupe mechanism, and what breaks when a consumer times out and retries a charge or a creation.

Pagination has a similar depth. Offset pagination is simple but breaks under concurrent writes and deep pages; cursor or keyset pagination is more stable but harder to implement and does not support arbitrary jumps. Know the trade-off and when each applies, rather than reciting one as correct.

Explain how the API evolves without breaking consumers

Versioning questions test whether you understand that a public API is a commitment. Adding optional fields is usually safe; renaming, removing, or changing the type or meaning of a field breaks consumers. Explain how you would introduce a breaking change: a new version, a deprecation window, or additive evolution that avoids the break entirely.

Prepare the practical answer: what you version, how you signal deprecation, and how long old versions live. 'We never break consumers' is not a strategy; it is a constraint the design has to respect. Interviewers want the mechanism, not the aspiration.

Worked example: designing a paginated list endpoint

Suppose you are asked to design an endpoint that returns a customer's order history. Start with the consumer's need: most recent first, filtered by status, paginated because histories grow. Then make each decision visible: cursor pagination because orders are written concurrently and offset gaps would corrupt the list, a consistent error shape, and a defined sort order with a tiebreaker so the cursor is stable.

The evaluated behaviour is the reasoning chain, not the specific answers. Each choice follows from a stated requirement, and each has a cost you name: cursor pagination costs arbitrary page jumps, stable ordering needs a unique tiebreaker, and filtering needs an index behind it.

I would use cursor pagination ordered by creation time with the order ID as a tiebreaker, because concurrent writes make offsets unreliable. The consumer gets a next cursor when more results exist and a consistent error shape when the cursor is invalid. Filtering by status adds an index requirement I would call out explicitly.

Rehearse designing one small API aloud

Pick a small, concrete service such as a URL shortener, a booking system, or an order history, and design its API aloud in fifteen minutes: resources, operations, request and response shapes, errors, pagination, idempotency, and evolution. The size forces prioritisation, which is what interviews evaluate.

Then defend it. Have someone ask: why this resource split, what breaks when you change that field, how does the consumer handle a retry? If you can justify each choice, you can survive an unfamiliar design prompt. If you memorised the pattern, the first constraint change exposes it.

Frequently asked questions

Practise the next answer

Use a Technical Deep-Dive or System Design Mock Session to rehearse designing an API aloud: resources, requests, responses, errors, and evolution, while answering follow-ups on breaking changes and consumer experience. Where a session includes the Code Pad, the AI Interviewer reads it but never executes code.

Practise for your job

Sources and scope

Employer sources describe their own processes, which may change. The exercises and illustrative examples are PrepRole editorial guidance, not employer questions or hiring criteria.

• Microsoft: REST API guidelines

Related guides

• Prepare the wider backend reasoning
• Place the API in an architecture discussion
• Prepare the data layer behind the endpoints