Skip to content
API Design Learn/Capstone Case Studies
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Design a Chat API

4 min read

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

Bidirectional streaming for live message 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

Conventional REST for history and setup, not real-time delivery
GET /conversations/501/messages?limit=50&before=msg_1200
GET /conversations/501/participants
POST /conversations

Loading 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

Delivery and read status as explicit, queryable fields on the message resource
{
  "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.

Press Run: the live receipt is missed, and the durable state recovers it

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.

Ready to Build This?

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.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!