Introduction: The API Design Interview

An API design interview does not test whether you know how to send an HTTP request. It tests whether you can design a contract that another program can use correctly, not only today, but years from now.

That contract is the visible boundary between a client and a server. It defines the operations the server offers, the inputs each one accepts, the outputs it returns, the ways it can fail, and the promises that remain true as the implementation changes.

The client could be a mobile application, another service, a partner company, or a script written by a developer you will never meet. The server could use one database today and a different architecture next year. As long as the contract stays the same, the caller should not need to care.

1. What Are You Designing?

Suppose an interviewer says:

"Design an API for a file-sharing service."

They are not asking only for a list of URLs. They want you to decide what a caller may do and what it can rely on. You may need operations to create a file record, upload content, retrieve metadata, list a folder, share a file, and revoke access.

Names alone are not enough. Each operation needs its required and optional inputs, and the contents of a success response. It needs a way to read a long list one page at a time, and different answers for a file that is missing and one that is forbidden. It needs a retry rule, and room to add a field later.

Those decisions form the contract. The implementation stays hidden behind it: a single read might reach a cache, a metadata database, an object store, and an authorization service, and the caller should not need to know.

2. One Skill, Several Interview Names

The same skill appears under different titles, and the title tells you which outputs the interviewer expects. There are two kinds.

The API design round is the plain form. You are asked for the contract itself: the resources, the operations, one operation in full detail, the failures, and the trade-offs. Nothing else is required.

The product architecture round, also called the product design round, asks for that same contract plus two additional deliverables. Companies that ship an application directly to end users tend to use this form, because their engineers argue about client behavior as often as about the contract.

The two additional deliverables are these.

The data model. Name the important entities and their relationships: for a messaging product, User, Conversation, Message, and Membership. The interviewer is not asking for database columns, but whether your model supports the questions the client needs to ask. A model with no concept of membership cannot express who may read or send messages.

The client call flow. Walk one screen through its calls, in order: load the conversation summary, request the first page of messages, subscribe to new-message events, send a message, then reconcile the pending message against the server's confirmed result.

That sequence reveals whether the contract works as a product. An API can look tidy operation by operation and still produce a slow application: if one screen needs twelve sequential calls, the contract created that latency, not the server.

API design is the general term throughout this course, and the extra product-architecture outputs are called out where they apply. Chapter 7 designs both of them in full.

3. API Design Is Not System Design

The two are related, and companies often test them in the same interview. They still ask different primary questions.

System design asks: will the system continue to work as traffic, data, and failure grow?

API design asks: can a stranger use this contract correctly for years?

Given "Design a file-sharing service," system design covers object storage, replication, caching, and availability during regional failures. API design covers a different set of questions: whether upload and metadata creation are one operation or two, how a caller lists a large folder, whether a missing file and a forbidden one answer differently, how a client resumes an interrupted upload, and how an old client survives new response fields.

Both require technical judgment. They apply it at different boundaries.

The distinction changes how you begin. System design starts by estimating traffic and identifying components; API design starts by identifying the callers and their jobs. If you do not know who is calling, you do not know what the contract must make easy.

The two constrain each other. An API promising immediate global consistency creates work for the system behind it. A system that completes work asynchronously needs job resources, status polling, or callbacks in its API.

4. What the Interviewer Is Really Testing

The interviewer is not checking whether you remember the "correct" URL. They are checking whether you can make careful decisions at a boundary other engineers will depend on. That means four things: you start from the caller rather than a database schema, you design failures as carefully as successes, you protect existing callers as the product changes, and you state trade-offs clearly enough that somebody can disagree with them. Lesson 4 covers each one as a graded signal.

There is rarely one perfect API. One candidate may combine two actions to reduce calls; another may separate them to keep permissions clearer. Either can earn a strong rating, provided the choice follows from the requirements and has a cost the candidate can name.

Interviewers cannot grade a decision they cannot see. Naming the alternative and its cost is what reveals judgment.

5. The Method You Will Use Throughout the Course

Every complete answer in this course follows the same six steps:

1. Identify the consumers and the jobs they need to finish.
2. Model the resources.
3. List the operations.
4. Design one operation in complete detail.
5. Address the hard parts, such as paging, retries, versioning, authentication, and rate limits.
6. State the trade-offs taken and the options rejected.

Lesson 5 gives the full framework with its minute budget. Notice the direction: it begins outside the server with the caller's job and ends with the cost of your decisions. The database does not choose the API, and a list of endpoint names is not a complete answer.

6. Map of the Course

The lessons build on one another, but the method stays fixed. Repetition is intentional. The goal is to make the sequence automatic, so you can still use it under time pressure.

Key Takeaways

• An API is the contract between a caller and a server: its operations, inputs, outputs, failures, and long-term guarantees.
• The round has two forms. The API design round asks for the contract. The product architecture or product design round asks for the contract plus a data model and a client call flow.
• System design asks whether the implementation keeps working as load and failure grow. API design asks whether callers can use the contract correctly as the product changes.
• Interviewers grade the decisions you make visible, so name the alternative and its cost.
• Every worked answer in this course follows the same six-step method.

You now know what the API design interview is and how it differs from system design. The next lesson steps back to the subject itself. What an API is, what its parts are called, how one call actually works, and why a published decision costs so much to reverse.