From one big app to many small services — and a chat app you could ship

1 HTTP APIs & REST design practices

An API (Application Programming Interface) is a contract: a set of requests one program promises to understand, and the responses it promises to give back. When that contract travels over the web, it almost always rides on HTTP (HyperText Transfer Protocol) — the same protocol your browser uses to load pages. A Web API is just an API you reach by sending HTTP requests to a URL.

The shape of an HTTP request

Every HTTP request has four parts: a method (the verb — what you want to do), a URL (what you want to do it to), optional headers (extra info like who you are), and an optional body (the data you're sending). The response comes back with a status code (did it work?), headers, and a body (the answer).

HTTP methods — the verbs

HTTP gives us a small set of verbs. Each says what kind of action you intend, which keeps APIs predictable.

Status codes — did it work?

The server replies with a three-digit status code. The first digit tells you the category at a glance.

Resources & URLs — the nouns

The dominant style for designing web APIs is REST (REpresentational State Transfer). Its core idea: model everything as resources (nouns), each living at a clean URL, and act on them with HTTP verbs. So you don't invent a verb-y URL like /createUser; you POST to the noun /users.

Statelessness

REST APIs are stateless: each request must carry everything the server needs to understand it (like a login token). The server does not remember anything about you between requests. This is exactly the same idea we met with LLMs being stateless — and it's powerful here for the same reason: any server in a fleet can handle any request, so you can add more servers freely (recall scaling from earlier sessions). The "state" (like your session) lives in a token you resend, or in a shared database.

Idempotency

Idempotency means: making the same request many times has the same effect as making it once. This matters because networks are flaky — if you don't get a reply, you might retry, and you don't want retries to create five identical orders.

• GET, PUT, DELETE are idempotent: reading twice is fine; replacing user 42 twice leaves the same result; deleting twice still ends with it gone.
• POST is not idempotent by default: two POSTs to /orders create two orders. The fix is an idempotency key — a unique ID the client sends so the server can recognise a retry and ignore the duplicate.

Versioning

Once real apps depend on your API, you can't just change it — you'd break them. So you publish a new version and keep the old one running. Common approaches: in the URL (/v1/users, /v2/users) or in a header (Accept: application/vnd.myapp.v2+json). URL versioning is the simplest and most common.

Good API design principles

• Use nouns, not verbs in URLs; let HTTP methods be the verbs.
• Be consistent: plural nouns (/messages), lowercase, hyphenated paths.
• Return correct status codes — don't reply 200 with an error inside.
• Filter/paginate big lists: GET /messages?limit=20&page=2.
• Version from day one so you can evolve safely.
• Clear error bodies: tell the caller what went wrong and how to fix it.

POST /v1/messages HTTP/1.1
Host: api.chatapp.com
Authorization: Bearer abc123
Content-Type: application/json

{
  "chat_id": 7,
  "sender_id": 42,
  "text": "Hello!"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/messages/9981

{
  "id": 9981,
  "chat_id": 7,
  "sender_id": 42,
  "text": "Hello!",
  "created_at": "2026-06-20T10:31:00Z"
}

2 Monolith vs Microservices

A monolith is an application built and deployed as one single unit. All the code — users, messages, billing, search — lives in one codebase, runs in one process, and ships together. Microservices is the opposite approach: you split the application into many small, independent services, each owning one area of the business, each deployed on its own, each talking to the others over the network (usually via the HTTP APIs from Topic 1).

What makes a service "micro"?

Not lines of code — it's about ownership and independence. A good microservice:

• Owns one area (e.g. "messages") and its own data store.
• Can be deployed, scaled, and even rewritten without touching the others.
• Talks to other services only through their public APIs — never by reaching into their database.

Bounded contexts — where to cut

The hard part is deciding the seams. The guiding idea is the bounded context (a term from Domain-Driven Design): a boundary inside which a set of words and rules has one clear meaning. The word "user" might mean a login account in one context and a billing customer in another — those are natural places to split. Cut along business capabilities, not technical layers. "Messaging," "Payments," "Notifications" are good services; "the database layer" is not.

Side by side

When to split (and when not to)

Start with a monolith. For a new product or small team, a monolith is faster to build, easier to debug, and has no network between parts. Split into microservices when you feel real pain:

• Different parts need to scale very differently (search is hammered; billing is quiet).
• Multiple teams keep stepping on each other in one codebase.
• You want to deploy parts on different schedules or in different languages.
• A bug in one area keeps taking down unrelated features.

3 Building a chat app with microservices

Let's design a simple chat application as two microservices. Keeping it to two makes the boundaries crystal clear and shows off the bounded-context idea from Topic 2.

The two services

How they fit together

The key design choice: the Message Service does not phone the Analytics Service and wait. It just stores the message, replies to the user immediately, and emits an event — a small "this happened" note. The Analytics Service picks that up on its own time. If analytics is slow or down, chatting still works perfectly. (We'll formalise this synchronous-vs-asynchronous choice in Topic 4.)

A real endpoint — the Message Service

Here's a small FastAPI service (FastAPI is a popular Python web framework) exposing the POST /v1/messages endpoint we designed in Topic 1.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from datetime import datetime, timezone

app = FastAPI()

# In a real service this is a database; a dict keeps the demo simple.
messages = {}
next_id = 1

class NewMessage(BaseModel):     # validates the request body
    chat_id: int
    sender_id: int
    text: str

def emit_event(name, payload):
    # Publish to a message queue (Topic 4). Fire-and-forget.
    print(f"event: {name} -> {payload}")

@app.post("/v1/messages", status_code=201)
def create_message(msg: NewMessage):
    global next_id
    if not msg.text.strip():
        raise HTTPException(status_code=400, detail="text required")

    record = {
        "id": next_id,
        "chat_id": msg.chat_id,
        "sender_id": msg.sender_id,
        "text": msg.text,
        "created_at": datetime.now(timezone.utc).isoformat(),
    }
    messages[next_id] = record
    next_id += 1

    # Tell the world a message was sent — Analytics will react later.
    emit_event("message.sent", {"chat_id": msg.chat_id,
                                "sender_id": msg.sender_id})
    return record        # FastAPI sends it back as JSON with 201

@app.get("/v1/chats/{chat_id}/messages")
def list_messages(chat_id: int, limit: int = 20):
    chat_msgs = [m for m in messages.values() if m["chat_id"] == chat_id]
    return chat_msgs[-limit:]

4 Inter-service communication

Once you have many services (Topic 2), they must talk. There are two big questions: what format do they use, and do they wait for the reply?

What format: HTTP/REST vs RPC (gRPC)

We met REST over HTTP in Topic 1 — human-friendly URLs and JSON. An alternative is RPC (Remote Procedure Call): you call a function on another service as if it were a local function (analytics.GetUserStats(42)) and the framework handles the network. The most popular modern RPC framework is gRPC (from Google), which sends compact binary data (using Protocol Buffers) over a fast connection.

Do they wait: synchronous vs asynchronous

This is the deeper choice. Both REST and gRPC are usually synchronous request/response: you call, you block, you get an answer. Asynchronous communication instead uses a message queue (a buffer in the middle, like RabbitMQ, Kafka, or AWS SQS): the sender drops a message and moves on; a receiver picks it up later. This is the "sticky note" model — exactly what our chat app used to feed the Analytics Service.

5 Handling image uploads in messages

People send photos in chat. The naive idea is to shove the image bytes straight into the messages database. Don't. A raw image file is a blob (Binary Large OBject) — and databases are terrible at storing big blobs.

Why not store blobs in the database?

• Bloat & slowness: images are huge compared to text. The database balloons, backups take forever, and queries that used to be instant get sluggish.
• Expensive: database storage and memory are far pricier per gigabyte than plain file storage.
• Bad at serving: a database can't efficiently stream a 4 MB photo to a browser the way a purpose-built file server can.
• Wasted cache: the database's memory should hold hot rows, not photo bytes.

The right way: object storage + CDN + a URL

Put the actual image in object storage — a service built to hold arbitrary files cheaply and durably (Amazon S3, Google Cloud Storage, Azure Blob Storage). Then store only a small URL / reference in the message row. To make downloads fast worldwide, serve those files through a CDN (Content Delivery Network) — a fleet of edge servers that cache copies of your files physically close to users (recall caching from earlier sessions; a CDN is caching for static files).

The upload flow

The clean pattern is a pre-signed URL: the client uploads the image directly to object storage (not through your service), so big bytes never clog your servers. Here's the flow.

import boto3, uuid
from fastapi import FastAPI

app = FastAPI()
s3 = boto3.client("s3")
BUCKET = "chatapp-images"

@app.post("/v1/uploads")
def create_upload(content_type: str = "image/jpeg"):
    key = f"img/{uuid.uuid4().hex}.jpg"   # unique file name

    # A temporary URL the client can PUT the image to directly.
    upload_url = s3.generate_presigned_url(
        "put_object",
        Params={"Bucket": BUCKET, "Key": key,
                "ContentType": content_type},
        ExpiresIn=300,                      # valid for 5 minutes
    )

    return {
        "upload_url": upload_url,         # client PUTs the bytes here
        # the public address to store in the message later:
        "image_url": f"https://cdn.chatapp.com/{key}",
    }

★ Putting it all together

You just learned how the pieces of a modern system talk to each other and how to build one. Here's the one-paragraph story connecting all five topics:

Quick self-check

📚 References & Further Reading

Class material

• 📄 Original course notes / handout (source sheet) — open the shared class material for this session.
• Class handout: "[SST-2028] Chat Application / Microservices".

Papers, docs & deep dives

• Martin Fowler — Microservices — the canonical definition and trade-offs of microservices vs monoliths.
• Richardson Maturity Model — a structured way to judge how RESTful an HTTP API really is.
• gRPC — Introduction — the high-performance RPC option for inter-service communication.
• Kafka: a Distributed Messaging System for Log Processing (original paper) — async messaging between chat services.