How to plan an integration between two systems

Decide which system owns each fact

For a booking workflow, the reservation system may own dates and guest counts, while a separate app owns how guests use their benefits. Write down who can change each field and which side should win if the systems disagree.

Give records a stable identity. A booking identifier lets the integration recognise a change to an existing booking instead of treating every message as a new booking. The exact identifiers and revision rules need to match the real APIs.

Map the full lifecycle

Include creation, changes and cancellation. A new booking may create access; a longer stay may extend it; a cancellation may withdraw it. These are different business decisions, not just different values in a payload.

Use a small table of examples to agree the expected result. Include a repeated message and an older update that arrives after a newer one. Confirm how the actual provider represents those situations before choosing an implementation.

Make a failed handoff recoverable

If the destination is down, the source change should remain visible and there should be an agreed way to recover. Depending on the system, that may involve a durable queue, bounded retries and a manual review path.

Repeated delivery must not create duplicate business effects. Do not promise exactly-once delivery across independent services. Define how the receiver recognises repeated work and how an operator checks uncertain outcomes.

Plan for the person operating it

A useful integration tells an operator what is waiting, what failed and which action is safe next. Logs should help diagnose the problem without exposing credentials or unnecessary personal information.

Agree who receives alerts, what they can retry and when they should contact the provider. Monitoring and a recovery procedure belong in the delivery scope, alongside the API connection itself.

Separate the demo from the technical investigation

Our booking demo uses fictional records and simulated failure. It shows the intended behaviour: the stay changes, the guest app temporarily holds an older value, and a retry brings it up to date.

Before connecting real systems, verify API access, authentication, rate limits, supported events, data handling and sandbox behaviour. Record unresolved assumptions in the architecture plan; they can change the estimate and delivery stages.