API Design Intro
An API (application programming interface) is the contract between a client and a server. It defines which requests the client can send and what the server returns for each one. In a system design interview, API design comes right after requirements gathering. Each functional requirement maps to one or more endpoints, which determine how data flows through the rest of the design. Interviewers usually expect a REST API, so this lesson starts there. The next lesson compares REST with GraphQL and gRPC.
The Parts of a Request
REST (Representational State Transfer) builds an API on plain HTTP. Each request contains a method, a path, and optional query parameters, headers, and a body. Each response returns a status code, headers, and a body.
The path names a resource—an entity in the system, such as a book or a user—while the method specifies the action to take on it. The path uses nouns, and the method acts as the verb:
| Request | Meaning |
|---|---|
GET /books | List the books. |
POST /books | Create a book. The server chooses its id. |
GET /books/{id} | Read one book. |
PUT /books/{id} | Replace one book with the body. |
PATCH /books/{id} | Change some fields of one book. |
DELETE /books/{id} | Delete one book. |
A related resource nests under its parent: GET /books/{id}/reviews lists the reviews of one book.
Try the API
The widget below simulates a small books API. Pick or type a request and send it to observe the status code, the response, and the server state.
Run these requests in order. Send POST /books two times, and two new books appear. Next, send DELETE /books/1 two times: the first returns 204 and the second returns 404, leaving the server state the same after both. Finally, send GET /getAllBooks, which puts a verb in the URL, and read why it fails.
Grasping the building blocks ("the lego pieces")
This part of the guide will focus on the various components that are often used to construct a system (the building blocks), and the design templates that provide a framework for structuring these blocks.
Core Building blocks
At the bare minimum you should know the core building blocks of system design
- Scaling stateless services with load balancing
- Scaling database reads with replication and caching
- Scaling database writes with partition (aka sharding)
- Scaling data flow with message queues
System Design Template
With these building blocks, you will be able to apply our template to solve many system design problems. We will dive into the details in the Design Template section. Here’s a sneak peak:
Additional Building Blocks
Additionally, you will want to understand these concepts
- Processing large amount of data (aka “big data”) with batch and stream processing
- Particularly useful for solving data-intensive problems such as designing an analytics app
- Achieving consistency across services using distribution transaction or event sourcing
- Particularly useful for solving problems that require strict transactions such as designing financial apps
- Full text search: full-text index
- Storing data for the long term: data warehousing
On top of these, there are ad hoc knowledge you would want to know tailored to certain problems. For example, geohashing for designing location-based services like Yelp or Uber, operational transform to solve problems like designing Google Doc. You can learn these these on a case-by-case basis. System design interviews are supposed to test your general design skills and not specific knowledge.
Working through problems and building solutions using the building blocks
Finally, we have a series of practical problems for you to work through. You can find the problem in /problems. This hands-on practice will not only help you apply the principles learned but will also enhance your understanding of how to use the building blocks to construct effective solutions. The list of questions grow. We are actively adding more questions to the list.