Introduction: The API Design Interview

An API design interview tests more than your ability to send an HTTP request. It tests whether you can design clear rules that other programs can use correctly, even as the product changes. These rules form the API contract.

The contract describes how a client and a server communicate. It defines the operations the server offers, the inputs each operation accepts, the outputs it returns, and the errors that can occur. It also explains which behaviors clients can depend on as the server changes.

The client could be a mobile application, another service, a partner company's system, or a developer's script. The server might use one database today and a different one next year. If the server continues to follow the contract, clients should not need to change because of that internal update.

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 client can do and what results it can expect. For a file-sharing service, this might include creating a file record, uploading content, reading file details, listing a folder, sharing a file, and removing someone's access.

Names alone are not enough. For each operation, define the required and optional inputs, the success response, and the possible errors. For a long list, explain how the client requests one page at a time. Explain when it can safely retry a request and how the API can change without breaking existing clients. Also decide what to return when a file is missing or access is denied. Sometimes the API should use the same error for both cases to avoid revealing that a private file exists.

These decisions form the contract. The client does not need to know how the server carries them out. For example, reading one file might involve a cache, a database, file storage, and a permission check. The API should hide those internal details while giving the client a clear result.

2. One Skill, Several Interview Names

API design skills can appear in interviews with different names. This course uses two formats to organize the discussion. Interview names and expectations vary by company, so confirm what your interviewer wants you to cover.

The API design round focuses on the contract: the resources, the operations, one operation in detail, the errors, and the benefits and costs of your choices. You may also discuss internal components when they affect the API's behavior.

The product architecture round, sometimes called the product design round, connects the API to the application that uses it. In this course, that means adding a data model and a client call flow. These help explain how the API supports a user's actions in the application.

These two additional parts answer different questions.

The data model. Identify the main types of data and how they relate. For a messaging product, these might be User, Conversation, Message, and Membership. Start with these relationships before discussing database columns. For example, membership records can show which users belong to a conversation and what they are allowed to do.

The client call flow. Explain the API calls a screen needs and their order. For example, a messaging screen might load a conversation summary, request the first page of messages, and subscribe to new-message events. When the user sends a message, the app sends a request and updates the message on the screen after the server confirms it.

This sequence helps you check whether the API supports the application well. Individual operations may look reasonable but still make a screen slow to load. For example, twelve calls that must run one after another add network waiting time, even if each server operation is fast. You may need to change the API or the call flow to reduce that delay.

API design is the general term used throughout this course. Lessons include the data model and client call flow where needed. Chapter 7 covers both in detail.

3. API Design Is Not System Design

API design and system design are related and may appear in the same interview. Their main areas of focus are different.

System design asks: how will the system meet its requirements as traffic and data grow or components fail?

API design asks: how can clients use this API correctly as the product changes?

For the question "Design a file-sharing service," system design might cover file storage, data replication, caching, and availability during a regional failure. API design might cover whether uploading content and creating a file record are one operation or two. It also covers how a client lists a large folder, handles errors, resumes an interrupted upload, and continues working when new response fields are added.

Both require technical judgment. System design focuses more on how the system works internally. API design focuses more on the behavior that clients can see and use.

Both types of interview begin by clarifying requirements. In system design, you then consider traffic, capacity, and the components needed. In API design, you focus on who will call the API and what those clients need to do. This helps you decide which operations the API must support.

Decisions in one area affect the other. If the API promises that a completed update is immediately visible in every region, the system must be able to provide that behavior. If the system accepts work and completes it later, the API needs a way to report progress or completion. For example, it could return a job ID that the client uses to check the status.

4. What the Interviewer Is Really Testing

The interviewer is not looking only for the "correct" URL. They want to understand how you make decisions that other developers will depend on. Four important skills are:

• Start with the client's needs, not only the database structure.
• Explain failures as carefully as successful results.
• Keep existing clients working as the product changes.
• Explain the benefits and costs of your choices.

Lesson 4 explains how these skills can be evaluated.

There is rarely one perfect API. One candidate may combine two actions to reduce the number of calls. Another may separate them to make permission checks clearer. Either choice can be reasonable if it meets the requirements and the candidate explains its disadvantages.

Explain your reasoning as you work. Name the main alternative, say why you did not choose it, and describe the disadvantage you accept with your chosen design.

5. The Method You Will Use Throughout the Course

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

1. Identify the clients and the tasks they need to complete.
2. Model the resources.
3. List the operations.
4. Design one operation in complete detail.
5. Address the difficult parts, such as pagination, retries, versioning, authentication, and rate limits.
6. Explain your choices, their disadvantages, and the alternatives you did not choose.

Lesson 5 explains the full method and suggests how much interview time to spend on each step. The method starts with the client's task and ends with the reasons for your design choices. A database structure or a list of endpoint names alone is not a complete API design answer.

6. Map of the Course

Each chapter uses ideas from earlier chapters, but the six-step method stays the same. You will practice it with different products so that you can use it more easily within the interview's time limit.

Key Takeaways

• An API contract defines the operations, inputs, outputs, errors, and behavior that clients can depend on.
• An API design interview focuses on that contract. In this course, product architecture questions also include a data model and a client call flow. Confirm the expected scope in your interview.
• System design focuses on meeting system requirements as traffic and data grow or components fail. API design focuses on how clients use the system as the product changes.
• Explain why you chose a design, what alternatives you considered, and what disadvantages you accept.
• Every complete worked answer in this course follows the same six-step method.

You now know what an API design interview covers and how it differs from system design. The next lesson explains what an API is, the names of its main parts, and what happens during an API call. It also explains why changing an API becomes harder once other programs depend on it.