Event-Driven Microservices API Platform
A reference architecture for REST and event-driven APIs side by side, with a schema registry, an API gateway and contracts that stay backward compatible.
The challenge
Running synchronous REST APIs and asynchronous events as one platform, without every team inventing its own contract style, versioning rule and error format.
Teams rarely choose between REST and events — they end up with both, and the problem becomes consistency. Two contract styles, two versioning conventions, two error formats and two discovery stories is what makes an integration take weeks instead of an afternoon. A platform of independently deployed microservices needs one answer to all four.
How it works
Both API styles are specified before they are built: OpenAPI for request/response, AsyncAPI for events. Both land in the same developer portal, so a consumer looking for “the order created event” and “the order lookup API” finds them the same way, with the same ownership and access-request path.
The schema registry is what makes the event side safe. Compatibility mode is enforced at publish time, so a producer physically cannot ship a field removal that would break existing consumers — the check is not a review comment, it is a failed publish.
The transactional outbox closes the gap that causes the worst class of bug in event-driven systems: a service that commits its state change and then fails before publishing the event, leaving downstream systems permanently out of step.
What to get right
- Additive changes only. New optional fields, never a removal or a type change. Breaking changes get a new topic or a new major version, not an edit.
- Consumer lag is an SLO. A consumer that is behind is an outage that has not been noticed yet.
- Design the dead-letter path first. Where a poison message goes, who is paged, and how it is replayed after the fix.
- Generate clients from the spec. Hand-written clients drift from the contract, and the drift is only discovered in production.
How it fits together
API gateway
Authentication, rate limiting, quotas and routing in one place. Consumers see a stable host and path; services behind it move, scale and get replaced.
Synchronous services
REST or gRPC for request/response — the reads a caller waits on. Specified in OpenAPI, and the spec is the source the client SDKs are generated from.
Event broker
The asynchronous backbone: partitioned topics, retention tuned per topic, and consumer groups that let a new subscriber be added without touching producers.
Schema registry
Every event payload has a registered schema and a compatibility mode. A producer cannot ship a breaking change, because the registry rejects it at publish.
Outbox and CDC
Services write state and the event to publish in the same transaction, and a change-data-capture reader relays it — so a crash cannot leave the two disagreeing.
Developer portal
One catalogue of both REST and event APIs, with ownership, environment, schema and a way to request access — the discovery layer of the platform.
Observability
Correlation IDs propagated across both the synchronous hops and the broker, plus consumer lag as a first-class SLO alongside latency and error rate.
Typically built with
- Kong
- Apache Kafka
- OpenAPI
- AsyncAPI
- Backstage
- Kubernetes
