API vs events vs batch: choosing an integration architecture

The right integration pattern depends on how quickly data must move, who owns the truth, and what happens when a system is unavailable. Start with those questions before choosing a message broker or API gateway.

Map systems and ownership

For each business object—customer, product, order, payment, or appointment—name its authoritative system and permitted writers. Draw the data flow and note sensitive fields. Agree on identifiers, validation rules, and what a successful transfer means.

Match the pattern to the need

Use a synchronous API when the user needs an immediate answer and both systems can meet the required availability. Use an event or queue when work can complete later and the producer should not wait for the consumer. Use scheduled batch exchange for large, non-urgent transfers where reconciliation is more important than instant updates. A hybrid design is common, but each boundary still needs one clear contract.

Plan failure behavior

Define timeouts, retries, idempotency keys, dead-letter handling, and manual recovery. Retrying a payment or notification without an idempotency rule can cause duplicates. Decide what the user sees when data is delayed. Monitor the age of queued messages, error rates, and reconciliation differences.

Protect change

Version contracts, test with realistic edge cases, and document who approves schema changes. Roll out an integration to a small traffic slice where possible. Keep a rollback path and a way to replay failed work safely.

A useful architecture decision record includes the business outcome, latency requirement, data owner, failure mode, security boundary, operational owner, and rejected alternatives. That document is more valuable than a diagram with no accountability.

Example: an order moving between systems

A storefront may need an immediate response when checking availability, so a synchronous API can be appropriate. Once an order is accepted, warehouse and notification systems can process events asynchronously. Finance may reconcile a daily batch against settled transactions. The patterns coexist because each step has a different latency and failure requirement.

Comparison questions

• Latency: Must the user wait for an answer, or can the work finish later?
• Coupling: What happens if the receiving system is unavailable?
• Consistency: Is temporary disagreement acceptable, and how will systems reconcile?
• Volume: Will bursts overwhelm an endpoint or queue consumer?
• Ownership: Which team changes and supports the contract?
• Audit: Can an operator trace a record across the whole flow?

Test the failure path

Disconnect a dependency in a test environment. Verify that the user sees an accurate state, retries do not duplicate actions, and operators can find and replay failed work. Write down the maximum acceptable delay and alert on it. A pattern is only suitable when the team can explain and operate its failure mode.

Compare the patterns in plain terms

A synchronous API gives an immediate response and is easy to reason about for a single request, but the caller waits for the dependency. An event lets producers continue while consumers process later; it needs monitoring, replay, and a plan for temporary inconsistency. A batch exchange is simpler for large scheduled transfers and reconciliation, but its information may be stale between runs. Webhooks are useful for notifying another system, yet the receiving side must validate, acknowledge, and handle duplicate delivery. Choose per data flow rather than declaring one pattern for an entire organization.

Design for retries and duplicates

A network timeout does not prove an operation failed; the server may have completed it before the response was lost. Use idempotency where an action must happen once. Stripe's API documentation provides a concrete example of idempotent request handling. Define retry limits, backoff, a dead-letter path, and a human recovery procedure. Test each with the operations team.

Contract and schema review

Publish the fields, types, identifiers, errors, and version rules for each interface. State which changes are backward compatible and how consumers will learn about them. Use contract tests around critical flows. Protect personal or financial data in transit and at rest according to the business requirement; do not copy fields merely because an API makes them available.

Migration without a sudden cutover

When replacing an existing integration, run the new flow alongside the old one where feasible. Compare records, timing, and exception rates. Agree on a cutover threshold and a rollback route. After the switch, retire the old path only after reconciliation is complete. The architecture decision is finished when teams can operate the integration through a failure, not when a happy-path demo passes.