Skip to content
API Design Learn/Event-Driven APIs
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Designing Domain Events

4 min read

You'll learn to

  • -Name events as past-tense facts rather than commands, and say why that keeps services decoupled
  • -Compare a thin event with a full snapshot, and see the staleness trade-off in a running example
  • -Give every event its own id, and keep an event catalog

An event-driven API communicates in a different way from request and response. Services publish events that describe things that have already happened, and other services subscribe and react, entirely decoupled from whoever produced the event. Designing the events well is as much a part of API design as designing REST endpoints or a GraphQL schema.

An Analogy: The Town Crier vs. the Boss

A boss tells a worker what to do: "ship order 501". That is a command, and the boss must know who will carry it out. A town crier announces "order 501 has shipped". That is a fact, and anyone who cares can react: the billing office, the customer notifier, the warehouse. The crier needs to know nothing about the listeners. Events are the crier.

Naming: Past Tense, Not Commands

An event describes something that already happened
{
  "event_type": "order.shipped",
  "event_id": "evt_7f3a2b1c",
  "occurred_at": "2026-08-07T14:30:00Z",
  "data": {
    "order_id": 501,
    "tracking_number": "1Z999AA10123456784",
    "shipped_at": "2026-08-07T14:30:00Z"
  }
}

Names should be past-tense facts (order.shipped, payment.completed), not imperative commands (ship_order, complete_payment). A command implies an instruction the receiver must obey, which ties the publisher to what subscribers should do. An event is just a statement of fact, and each subscriber decides whether and how to react. It is the decoupling idea behind the Observer pattern from LLD, applied between services instead of between objects.

Payload Design: Thin Reference vs. Full Snapshot

Thin: just enough to identify what changed
{"event_type": "order.updated", "order_id": 501}
// subscribers that need details must call back to fetch the current order
Full snapshot: the complete relevant state at the moment of the event
{
  "event_type": "order.updated",
  "order_id": 501,
  "status": "shipped",
  "total": 149.99,
  "items": [{"product_id": 42, "quantity": 2}]
}
// subscribers get everything they likely need without an extra round trip

A thin event stays small and never ships stale data, because subscribers fetch the current state when they act. The price is an extra API call from every subscriber that needs details. A full-snapshot event saves that call, but the data can be stale by the time a subscriber processes it, especially after a retry or a delay, and every subscriber becomes tied to the exact shape the publisher chose to include. The demo shows both. An order is shipped, then moves on to delivered before a slow subscriber looks at its events.

Press Run: the thin event leads to fresh data, the snapshot to a stale view

Neither is always right. The choice depends on how many subscribers need the detailed data, and how well they tolerate slightly stale values.

An Event Catalog

As a system gains dozens of event types across many services, an explicit, documented catalog becomes as important as REST's resource documentation or a GraphQL schema. It lists what events exist, their exact payload shapes, and who publishes each. Without one, "does an event for this already exist?" becomes tribal knowledge, and teams publish near-duplicate events because nobody could find the original.

Give every event a unique event_id, separate from the business entity's own id such as order_id. It is what lets the idempotent-consumer patterns later in this module detect and ignore a duplicate delivery of the same event.

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 Event Storm in the API Design Lab's gRPC & Event-Driven 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!