The first successful API request is a satisfying moment. The credentials work, the response looks sensible, and something that lived in one system can now appear in another.

I enjoy that part. I also think it's very easy to mistake it for most of the job.

Once an integration has real people relying on it, the difficult questions tend to involve what the records mean, who can change them, and what happens when the two systems disagree. I'd rather work through those questions while the integration is still a conversation.

Which record are we talking about

Suppose we're connecting a customer database to a service platform. Both have a customer record. That sounds promising until we discover that one customer can have several sites, each site has its own contact, and the other system uses the word customer for the company paying the invoice.

Before mapping any fields, I want to understand those relationships.

I also want a reliable way to recognise a record on the next import. A name is easy to change. An email address might be shared or corrected. Where a provider offers a stable identifier, I'd usually store it explicitly and keep its meaning clear.

That mapping becomes particularly useful when someone asks why an update affected a particular record. We need to be able to trace the connection without reconstructing it from matching names.

Who gets to change each value

Calling one application the source of truth is useful, but I often need a more detailed answer.

The accounts system might own the billing address while the service platform owns access instructions. A member of staff might correct a phone number locally. We then need to decide whether the next import preserves that correction or replaces it.

I'd write those decisions down against the fields involved. Otherwise, whichever job runs last can quietly become the authority.

Empty values deserve the same attention. An omitted field, an explicit request to clear a value, and an empty string can mean different things. Treating all three as equivalent is an efficient way to erase information somebody spent time entering.

What happens when we receive it twice

I want to know how an integration behaves when work is repeated, including after a timeout where we don't know whether the other system accepted our request.

Some providers explicitly expect this. Stripe documents that webhook events can arrive more than once and that delivery order isn't guaranteed. Its webhook documentation makes those conditions part of the integration contract.

For an incoming update, I'd want repeated processing to leave the record in the intended state. For an operation that creates something elsewhere, I'd check what support the provider offers for safely identifying the same operation across retries.

Those are separate decisions. Adding a retry loop doesn't tell us whether repeating the request is safe.

Who notices when it stops

A failed integration needs to be understandable to somebody who didn't write it.

That means keeping enough context to identify the affected record and operation, while being deliberate about what information goes into logs. A provider reference and a useful error can be more valuable than an entire customer payload.

I'd also distinguish a rejected record from a connection failure. One might need someone to correct an address. The other might need the job to wait and try again. Presenting both as a generic sync error leaves the next person doing the investigation from scratch.

The recovery action matters too. Can we retry one record? Will that repeat something that already succeeded? Can staff see whether the information they're looking at is current?

These questions affect the interface as much as the PHP behind it. An integration becomes part of somebody's working day, and they need enough information to decide what to do next. That's the point where I want the design to hold up.