The whole course ▾
System Design · Lesson 3 of 39 · Week 1
APIs and data models: the contract of a system
QuickBite's app and server must speak the same language. Today: designing APIs and data models that never break under pressure.
Got a doubt? Ask in the comments under the video.Subscribe
QuickBite's order API, and its tables: users, restaurants, menu items, orders.
QuickBite is the food delivery app we grow through the course, from one server to millions of orders.
The API contract
In our last two lessons, we looked at how a request travels and the numbers that define our limits. Today, we focus on the contract between the customer's phone and the QuickBite server.
Imagine a customer wants to order a burger. The app sends a message to the server. But if the app sends a field called price_in_cents and the server is looking for a field called amount, the system breaks. This is why we need an API, or Application Programming Interface. It is a formal contract. It says: if you send me data in this exact shape, I promise to give you a result in that exact shape. Without this agreement, we cannot build a system that scales or even one that works.
REST and resources
Most web APIs follow a style called REST. It treats everything in our system as a resource.
In REST, we use standard HTTP verbs to act on resources. To create a new order in QuickBite, the app sends a POST request to slash orders. Step one: the request arrives with the burger details. Step two: the server creates the order and sends back a 201 Created status code. If the user wants to check their order later, they send a GET request to slash orders slash one-two-three. We use POST for creating, GET for reading, PUT for updating, and DELETE for removing. It is a simple, universal language that every developer understands.
Status codes are how the server talks back. Two hundred means success. Four hundred codes mean the client made a mistake, like forgetting the restaurant ID. Five hundred codes mean the server crashed. In an interview, using the right code shows you respect the protocol. Don't just say 'it returns an error'; say it returns a 400 Bad Request.
Pagination and Idempotency
As QuickBite grows, two problems appear: we have too many orders to show at once, and sometimes, users click the 'Order' button twice.
If a user has a thousand past orders, we don't send them all in one GET request. That would be too slow. We use pagination. You might know 'offset' pagination, where you ask for page two, but that breaks if a new order is added while you're scrolling. Instead, we use cursor pagination. We send the user ten orders and a 'cursor', which is just the ID of the last order they saw. The next request asks for orders after that ID. It is faster for the database and it never skips an item.
Now, what if the network is slow? The user taps 'Order', the request reaches the server, but the connection drops before the 'Success' message gets back. The user taps again. To prevent charging them twice, we use an idempotency key. The app generates a unique ID for that specific attempt. If the server sees the same key twice, it knows the second one is just a retry. It returns the same success message without creating a second order. We will see this again in Lesson 17, but for now, remember: idempotency makes retries safe.
GraphQL, gRPC, and WebSockets
REST is great, but it isn't the only tool in the box. Sometimes we need a different kind of connection.
If our app needs to show a complex screen with user info, restaurant details, and menu items all at once, REST might require three different requests. GraphQL allows the app to ask for exactly what it needs in one go. For communication between our own servers, we often use gRPC. It uses a binary format that is much faster than the text-based JSON in REST. And for the live map where you see the rider moving? We use WebSockets, which we'll cover in Lesson 18. It keeps a connection open so the server can push updates to the phone instantly.
Data modeling
The API is the contract for the outside world, but the data model is the contract for our database. It's how we store the reality of QuickBite.
Think of our core entities. We have Users, Restaurants, and Orders. Each one needs a Primary Key—a unique ID like user-id. They also have relationships. One user can have many orders, which we call a one-to-many relationship. On the board, we represent this by putting the user-id inside the order record as a Foreign Key. This structure is the foundation of a Relational Database like Postgres, which we'll use for QuickBite's orders because we need strict consistency.
When do you choose NoSQL? Imagine our menu items. One restaurant has burgers with 'extra cheese' options, another has pizzas with 'crust' options. A Document Database like MongoDB is great here because it doesn't force every item into the same rigid columns. For very simple lookups, like looking up a session token, we use a Key-Value store like Redis. In an interview, your choice of database should always depend on the shape of your data and how you plan to query it.
In the interview
Here is how to handle the 'API and Data Model' step in a real interview.
Say this early. It shows you don't just jump into drawing boxes; you think about the data first. Interviewers love candidates who define the 'what' before the 'how'.
Don't make these mistakes. If you're designing a payment or order system, always mention idempotency. If you're listing thousands of items, always use cursors. These are the marks of a senior engineer who has seen things break in production.
Quick check
Why is cursor pagination better than offset pagination for a busy app like QuickBite?
Show the answer
It handles new data being added while scrolling without skipping or duplicating items.
Three things to take away. REST is our standard language. Idempotency keys are non-negotiable for critical actions. And your data model—SQL or NoSQL—must match how your app actually reads the data. Master the contract, and the rest of the system becomes much easier to build.
Lessons on weekdays, the week's revision on Saturday, a mock interview on Sunday.