Web app development
Two systems agreeing on a field name does not mean they agree on the truth.
The short answer
A dependable API integration starts by naming which system owns each fact and what event should move it. Map identities and states before fields, design for duplicate messages and temporary failure, keep a traceable record of every transfer and release the integration beside a manual recovery path until its behaviour is proven.
Integration work looks like plumbing from the outside. The difficult part is deciding what each system is allowed to believe, which one wins when they disagree and how a person recovers when the automated path stops halfway through. Those are business rules expressed through software, and they need owners before they need endpoints.
Name the source of truth for every important fact.
A customer may exist in a sales tool, a billing platform, a support system and the product itself. Copying every field in every direction creates four partial authorities and no safe place to correct an error. Decide which system owns identity, contact information, commercial status, access and each operational record.
Ownership can differ by field. Sales may own the account name while billing owns payment status and the product owns usage. The integration should move each fact from its owner to the systems that need it, not let the latest timestamp overwrite a more authoritative source.
Write the consequence of disagreement. Does a suspended billing account remove product access immediately? Can support correct an email address, or must it request a change from the customer system? These questions look small until an automated update affects the wrong person.
Map events and identities before mapping fields.
Field mapping is visible and therefore gets attention. Identity is quieter and more dangerous. The same company may have different internal numbers, duplicate records or several contacts with similar names. A reliable integration needs a stable way to match the same entity across systems and a review path when the match is uncertain.
Then define the events that cause movement. A record created, a status changed, an approval completed, a payment failed or a scheduled reconciliation ran. Each event needs a direction, the minimum data required and a statement of what happens if the receiving system is unavailable.
1. Inventory the records
List the people, accounts, transactions and operational objects that cross the boundary. Include the identifiers each system already uses.
2. Assign field ownership
Mark the authoritative system for every consequential fact and whether other systems may propose or only consume a change.
3. Define the triggering events
State exactly what starts a transfer and which later changes should update, reverse or ignore it.
4. Write the exception queue
Decide who reviews unmatched records, rejected updates and conflicts. Automation without an accountable queue only hides manual work.
Assume messages repeat and systems disappear temporarily.
Networks fail after the receiving system completes a request but before the sender hears the answer. A retry can then create the same order, payment or contact twice. Every important operation should carry a stable identifier so repeating the same request produces the same result rather than a duplicate.
Retries need limits and spacing. An unavailable system should not receive thousands of immediate repeats from every queued record. Hold the work, back off, alert the responsible person and preserve enough context to continue safely when the dependency returns.
Do not turn every failure into a generic support ticket. Separate temporary connection problems, rejected data, expired access, rate limits and business conflicts. The response is different for each, and the person responsible needs a useful explanation rather than the raw error returned by another system.
| Failure | Automatic response | Human response |
|---|---|---|
| Temporary outage | Queue and retry with increasing delay | Act only when the delay exceeds the agreed window |
| Duplicate message | Return the result of the original operation | Review only if the payload conflicts |
| Invalid data | Reject without repeated retries | Correct the source record or mapping |
| Unmatched identity | Hold the transfer without guessing | Link or create the record through an accountable queue |
Make every transfer traceable without exposing sensitive data.
An operator should be able to answer whether an event left the source, reached the destination and changed the intended record. Give each transfer a trace identifier that appears in logs and support views. Record timestamps, system responses and safe metadata, while keeping credentials and sensitive payloads out of general logs.
Monitoring should describe the business flow as well as the connection. A green server can still leave a growing queue of rejected records. Track queue age, failure type, unmatched identities and the completion of the event that matters. Alert the person who can act, with enough context to choose the next step.
Credentials need clear ownership, restricted access and a rotation process. Use supported authentication methods and keep secrets outside the code. A future team should be able to replace a credential without reverse-engineering how the integration was deployed.
Release beside reconciliation, then remove the manual bridge deliberately.
Start with a narrow group of records or one event type. Compare the source and destination after each run, and keep a manual way to correct a missed or incorrect transfer. A full cutover before reconciliation works is an efficient way to distribute an unknown error across the whole business.
Run an explicit reconciliation that asks which records should match and lists the ones that do not. That report is part of the integration, not a temporary spreadsheet to discard after launch. It catches quiet failures that neither system considers an error.
We treat the integration boundary as a product surface. The people operating it need status, explanations and recovery controls. Once the automated path has earned trust, retire duplicate manual entry and document the remaining exceptions instead of leaving both systems active forever.
Before removing the old process, reconcile a meaningful period of real activity and have the operational owner sign off on the exceptions. A technical success rate cannot decide whether the remaining mismatches are harmless or whether they change a customer, payment or compliance record that the business depends on.
Worth knowing before you start
Put the authoritative system beside every important field before anyone draws an arrow between applications.
Use stable operation identifiers so a safe retry cannot create the same real-world action twice.
Build an exception queue with an owner. Failed automation is still work, and hidden work gets missed.
Keep reconciliation after launch. A successful request does not prove the two systems still agree.
Related work
Common questions
Document the records crossing the boundary, the authoritative system for each field, stable identifiers, triggering events, accepted states, authentication, failure responses, reconciliation and the person responsible for exceptions. An endpoint list describes access. It does not describe the business rule the integration must preserve.
Use a stable identity for the real entity and an idempotency key for each operation. If the same message arrives twice, the receiving side should return or update the original result instead of creating another one. Uncertain identity matches should enter review rather than being guessed automatically.
Queue work that can wait, retry it with increasing delay and show how old the queue has become. Stop repeating failures that need corrected data or access. Preserve a manual recovery path for consequential work and alert someone when the agreed delay is exceeded.
Monitor completed events, queue age, rejected records, unmatched identities and reconciliation differences. Server availability is only one signal. The useful measure is whether the business event reached the right record in the destination and can be traced when it did not.
Related
Want to talk through your situation?
A short call is usually enough to tell whether this is the right work for you. If it isn’t, we’ll say so.