API guide
Event-driven integration
An API call says "do this now and tell me the answer". An event says "this happened". When many systems need to react to the same thing, events keep them loosely connected: the sender does not need to know who is listening.
Use calls forQuestions needing an answer now
Use events forNews others react to
BrokersKafka, RabbitMQ, NATS
ConsumersMust be idempotent
Call or event?
| Situation | Use | Example |
|---|---|---|
| Caller needs an answer to continue | API call | Check stock before confirming an order |
| Several systems react to the same thing | Event | "Order placed" updates warehouse, billing and notifications |
| The receiver may be offline for a while | Event | A branch system that syncs every few minutes |
| Very high volume of updates | Event stream | Tracking pings from thousands of vehicles |
Doing it reliably
- Outbox pattern: save the change and the event in the same database transaction, then publish, so you never update the database without telling others.
- Idempotent consumers: messages can arrive twice. Processing the same event twice must be harmless.
- Schemas: describe events with a schema and a registry, and evolve them without breaking consumers.
- Dead-letter queues: messages that keep failing go aside for a person to inspect, instead of blocking the rest.
- Ordering: decide where order matters, and partition events by the right key, such as order ID.
Typical tools
| Need | Common choices |
|---|---|
| High-volume event streams | Apache Kafka |
| Work queues and routing | RabbitMQ |
| Lightweight messaging | NATS |
| Schemas | AsyncAPI, a schema registry with Avro or JSON Schema |
More API guides: API design and gateway · Monolith or microservices? · API security · API FAQ · Use case: partner APIs
Untangling integrations, or opening APIs to partners?
Tell us which systems need to talk, who will call your APIs, and what breaks today. We will come back with a plain view of the right structure, what to change first, and what to leave alone.