Architecture pattern
Event-driven integration behind an API front door
Let partners and apps publish and receive events through familiar, governed HTTP APIs, while an event broker does the fan-out behind the gateway.
- Caller
- Gateway
- Component you run
- Control, identity or policy
- Request
- Event or background
How it flows
- Partner systems to API gatewayPublishes an event as an HTTPS request, authenticated like any other API call.
- API gateway to Schema registryValidates the payload against the registered schema and rejects bad events early.
- API gateway to Event brokerProduces the event to a topic and returns an acknowledgement.
- Event broker to Order processing and Analytics (asynchronous)Consumers read at their own pace and can replay from an offset.
- Event broker to Event delivery (asynchronous)Selected topics feed an outbound delivery service.
- Event delivery to Client apps (asynchronous)Pushes events to subscribers, with retries and signed payloads.
The problem
Event streaming platforms such as Kafka are excellent inside the organisation, but exposing them directly to partners or client apps is hard. Native protocols need special clients, firewall changes and broker-level credentials. Meanwhile many integrations are still point-to-point HTTP calls that break whenever one side is slow.
When to use it
- External parties need to send or receive events but should not connect to the broker directly.
- Several internal consumers need the same events, at their own pace.
- You want the same authentication, quotas and analytics for events as for your REST APIs.
- Producers and consumers should be decoupled, so a slow consumer does not slow the producer.
When not to
- The caller needs an immediate, consistent answer, such as checking a balance before a payment. Use a synchronous API.
- Very high-throughput internal streams between services that already speak the broker's protocol. Putting HTTP in the middle adds cost without benefit.
- When nobody owns event contracts. Without schemas and versioning, events become an undocumented coupling.
Key components
- API gateway as front door. Authenticates publishers, applies quotas, and translates HTTP requests into produce calls on the broker.
- Schema registry. Holds event contracts, so bad payloads are rejected at the edge rather than poisoning a topic.
- Event broker. Stores events durably and lets each consumer group read and replay independently.
- Outbound delivery. Webhooks, server-sent events or WebSocket connections that push selected events to subscribers, with retries and signatures.
- Catalogue. A shared place where teams discover both APIs and event streams, often described with OpenAPI and AsyncAPI.
Trade-offs
- Eventual consistency. Accepting an event is not the same as processing it. Clients must handle "accepted" and check outcomes later.
- Ordering and duplicates. Most brokers guarantee order only within a partition, and delivery is usually at least once. Consumers must be idempotent.
- Webhook reliability. Outbound delivery needs retries, back-off, dead-letter handling and a way for subscribers to catch up.
- Two governance models. API and event governance must line up, or the front door becomes a translation layer nobody understands.
Explore further
Lab: One request, eight plugins.→Follow a single AI request through an ordered chain of gateway plugins, switch any of them off and see what changes.