Events Are Contracts Too

This module has treated REST as the API, but modern systems talk asynchronously too - the domain events and message queues from earlier modules. Here's the lesson teams learn painfully: an event is every bit as much a contract as a REST endpoint. The moment billing publishes an InvoicePaid event that other services consume, its shape is a promise, and changing it carelessly breaks consumers you may not even know about. Async APIs need the same discipline as sync ones - plus a few tools of their own.

Why events feel deceptively safe

A REST response goes to a caller you can picture. An event goes to a topic, and anyone can subscribe - now or in the future. That invisibility makes events feel private and changeable, which is exactly the trap:

// billing publishes this to the "invoices" topic
{ "invoiceId": "INV-42", "orderId": "ORD-7", "amount": "50.00", "currency": "USD", "paidAt": "..." }

Three services you've forgotten about consume it: fulfillment triggers shipping, analytics aggregates revenue, loyalty awards points. Rename amount to amountPaid and all three break silently - no compile error, no failed HTTP call, just consumers quietly misbehaving. The published event schema is a contract with every current and future subscriber, and it deserves the same care as a REST payload - arguably more, because the consumers are even less visible.

Schema compatibility rules

The same breaking/non-breaking distinction from the versioning lesson applies, now governed formally by a schema (Avro, Protobuf, or JSON Schema) with defined compatibility modes:

• Backward compatible - new consumers can read old events (e.g. you added an optional field with a default). New schema reads old data.
• Forward compatible - old consumers can read new events (they ignore the new field - tolerant reader again). Old schema reads new data.
• Full - both directions hold.

The practical rules mirror REST evolution: adding an optional field with a default is safe; removing a field, renaming one, or changing a type is breaking. Serialization formats like Avro enforce this - a field needs a default to be safely addable, and the format is designed so old and new readers coexist.

The schema registry

Who enforces these rules across independently-deployed producers and consumers? A schema registry (e.g. Confluent Schema Registry for Kafka). Producers register a schema version before publishing; the registry rejects an incompatible schema change according to the configured compatibility mode:

producer wants to publish v2 of the InvoicePaid schema
        │
        ▼
   Schema Registry: is v2 BACKWARD-compatible with v1?
        ├─ yes → accept, assign version, allow publishing
        └─ no  → REJECT - the producer's deploy fails, before any bad event is emitted

This is the async equivalent of consumer-driven contract testing: an automated gate that stops a breaking change at deploy time rather than discovering it via corrupted downstream data. Messages carry a small schema id, so consumers fetch the exact writer schema and deserialize safely even as schemas evolve.

The async-contract discipline, summarized

Treat events like the public API they are:

• Design the event schema deliberately - it's a contract, not an internal dump. Don't serialize your domain entity onto the topic (the same "don't leak the entity" rule as REST).
• Evolve it compatibly - additive changes with defaults; version the schema when you must break it.
• Enforce with a registry - let it reject incompatible changes automatically.
• Make consumers tolerant readers - ignore unknown fields so producers can add them freely.
• Include an event version and a stable event type so consumers can route and adapt.

(There's even an OpenAPI equivalent for events: AsyncAPI, a machine-readable spec for message-driven APIs.)