# Choosing API, event or batch integration

**NR-007** · Decision guide · v1.0.0 · Reference / illustrative

Pick an integration style based on interaction semantics, consistency, latency and recovery—not because a platform supports a particular technology.

![Choosing API, event or batch integration](diagram.svg)

## Architecture problem
Teams frequently use synchronous APIs for loosely coupled broadcasts, events for commands, or batch for workloads that require transactional feedback.

## Apply when
- Reviewing enterprise integration designs
- Choosing between request-response, domain events and scheduled data movement
- Documenting integration reliability requirements

## Not intended for
- Replacing detailed transaction design with a yes/no flowchart
- Using events as an excuse to avoid ownership
- Assuming every interface fits only one pattern

## Design rules
1. Need a response now? Prefer a synchronous API or request/reply contract.
2. Publishing a completed fact to many consumers? Prefer a domain event with durable delivery.
3. Moving large datasets on a tolerance window? Consider batch or CDC.
4. All patterns need identity, schema versioning, retries, dead-letter handling where relevant, observability and ownership.
5. Model hybrid flows explicitly: command via API, event after commit, analytics via CDC.

## Trade-offs
- Synchronous calls offer immediate feedback but introduce temporal coupling.
- Events support decoupling but demand idempotency and eventual-consistency design.
- Batch is efficient for volume but trades freshness and granular failure handling.

## Review questions
- Is this a command, query, notification or bulk movement?
- Which party owns successful completion?
- What ordering, duplication and consistency guarantees are needed?
- What happens when the receiver is down for six hours?

## Download / adapt
- `diagram.drawio` — primary editable diagrams.net file
- `diagram.dot` — independent Graphviz concept source
- `diagram.mmd` — editable Mermaid interpretation
- `diagram.svg` — scalable figure
- `diagram.png` — high-resolution figure
- `metadata.yaml` — structured pattern description

**Reuse:** CC BY 4.0; credit nishtnr, link the license, and indicate changes. Conceptual reference only.