Design a Chat API
You'll learn to
- -Split a chat API between a live streaming connection and a REST API, and justify each
- -Store delivery status and read receipts as durable fields, so a reconnecting client recovers them
- -Run an offline user missing a live receipt and recovering it from history
A chat API is a real-time problem wrapped around a fairly ordinary set of resources: conversations, messages and participants. That makes it a good test of whether a candidate picks the protocol that fits each part of the problem, instead of forcing one protocol to do everything.
An Analogy: The Phone Call and the Message Book
A phone call is live: you talk and listen at the same moment, and if the other person is not there, you miss them. A message book on the table is durable: anyone can read the whole history whenever they come back. A chat app needs both. Live delivery is the call. Loading old messages, and checking whether a message was read, is the book.
Step 1-3: Clients, Resources, and a Deliberately Mixed Protocol Choice
The clients are a mobile and a web app. They need real-time delivery of new messages, and also the ability to load history when a conversation first opens. That naturally splits into two protocols and not one. A persistent two-way connection carries live messages, using gRPC bidirectional streaming or a WebSocket depending on platform limits. A conventional REST API handles everything that is not inherently real time: fetching history, managing participants, searching old messages.
Real-Time Delivery
service ChatService {
rpc Connect (stream ClientMessage) returns (stream ServerMessage);
}
message ClientMessage {
oneof payload {
SendMessage send = 1;
MarkAsRead read_receipt = 2;
TypingIndicator typing = 3;
}
}One bidirectional stream, from the gRPC streaming chapter, carries every real-time event in both directions: outgoing messages, read receipts and typing indicators. It uses oneof, from the wire-format chapter, to represent the different kinds of client event over a single connection, instead of needing a separate stream for each.
REST for Everything Else
GET /conversations/501/messages?limit=50&before=msg_1200
GET /conversations/501/participants
POST /conversationsLoading the last 50 messages when a user opens a conversation, or listing participants, has no real-time element. It is a normal paginated fetch, using cursors from the pagination chapter. Pushing it through the live streaming connection would add complexity for no benefit over a plain REST call.
Presence and Delivery Status as Queryable State
{
"id": "msg_1201",
"sender_id": "user_42",
"text": "Hey, are you free later?",
"sent_at": "2026-08-07T14:00:00Z",
"delivery_status": "read",
"read_by": [{"user_id": "user_99", "read_at": "2026-08-07T14:01:30Z"}]
}Delivery status and read receipts should not be purely momentary signals, lost the instant a client is not connected to receive them. Store them as durable fields on the message resource, so a client that reconnects after being offline can fetch the correct current state over REST, instead of having missed a live event for good. The demo shows this. Ann's phone loses its connection just as Bob reads her message. She misses the live receipt, but the history still has it. The last lines show paging backwards through history with a cursor.
A strong signal on this prompt is to justify the REST-plus-streaming split out loud, instead of defaulting to streaming for everything. Saying "this part does not need real-time delivery" is exactly the protocol-choice judgment the course's opening module set up as the skill being tested.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design a Chat API in the API Design Lab's Full System Design act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!