The whole course ▾

System Design · Lesson 3 of 39 · Week 1

APIs and data models: the contract of a system

Updated 22 Oct 2026 · By Akshay, software engineer, India · 5 min read

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 in this lesson

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

The API contract
Customer App
QuickBite
Server
Create Order
Unknown field:
price_in_cents

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

REST and resources
Customer
Orders API
POST /orders
1
201
Created
2
GET /orders/123
3
Common Status Codes
->
200 OK: Everything worked
->
201 Created: New resource made
->
400 Bad Request: Client sent
garbage
->
404 Not Found: It doesn't exist
->
500 Server Error: We broke
something

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

Pagination and Idempotency
App
Server
GET /orders?cursor=abc
1
Orders + next_cursor
2
Cursor: last ID seen
Pagination and Idempotency (cont.)
User
Order
Service
POST /orders (Key: XYZ)
1
POST /orders (Key: XYZ)
2
Already processed XYZ

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

GraphQL, gRPC, and WebSockets
REST
Simple and standard
Can fetch too much data
One request per action
Alternatives
GraphQL: Client picks fields
gRPC: Fast server-to-server
WebSockets: Real-time stream

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

Data modeling
Users
PK: user_id
Restaurants
PK: rest_id
Orders
PK: order_id
1:N
1:N
Relational (SQL)
Strict schema (Tables)
Great for complex queries
Best for financial data
Non-Relational (NoSQL)
Flexible (Documents)
Easier to scale out
Best for fast-changing data

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

In the interview
SAY THIS IN THE INTERVIEW
I'llstartbydefiningthe
APIendpointsandthe
dataschematoestablish
aclearcontract.
Interview Mistakes
Forgetting status codes
Using offset pagination for large lists
No idempotency for payment actions

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

Quick check
?
Why is cursor pagination better than
offset pagination for a busy app like
QuickBite?
It handles new data being added while
scrolling without skipping or duplicating
items.
Remember
REST verbs and status codes are the
standard
Idempotency keys make retries safe
Pick your DB based on the query pattern
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.

Practise with flashcardsYour progress stays on this device.
New System Design videos at 6 pm

Lessons on weekdays, the week's revision on Saturday, a mock interview on Sunday.