The API that was not ready
On one programme we integrated with Salesforce, and the client's API was not ready when we had to design and build. The price and the timeline were fixed and the team was staffed, so waiting was not an option. We designed and built the integration on assumptions about how the API would behave.
When the client's API was really ready, we reworked the integration. I do not count that as a failure. It was the price of keeping the team moving, and we knew we might have to pay it. What mattered was whether the rework was small and whether anyone was surprised by it.
Why design cannot always wait
The other system is usually owned by someone with their own priorities and their own plan. If the design waits for it, the vendor's team waits too, and on a fixed price that wait comes out of the vendor's budget. A design built on explicit assumptions is a loan: it buys time now and is repaid later, so the only real question is how large the repayment is.
The opposite mistake is just as real. A team that designs on assumptions and says nothing is building a surprise for later. The client should know which parts of the design rest on a guess, and roughly what it would take to change them.
How I keep the rework small
- Isolate the integration. Everything that depends on the external system sits behind one layer, so a change touches one place.
- Write the assumptions down. Fields, formats, error behaviour, authentication, expected volumes, each with a client-side owner who can confirm it.
- Test against a stand-in. A simple mock built from the assumptions lets the team test early, and it shows exactly what we believed.
- Put the rework in the plan. Name it in the RAID log and reserve time, so it is a planned event and not a surprise.
None of this is an argument for building carelessly. It is an argument for being clear about which parts of the design are firm and which are provisional, and for labelling them that way in the documentation, so that a new team member reads the status of each decision along with the decision itself.
Confirm the expensive ones first
Not every assumption deserves the same attention. I rank them by how likely they are to be wrong and how much a mistake would cost. The way two systems authenticate, or the shape of the data they exchange, goes first. I take those questions to the client's technical owner early, usually in the technical sync, while the rest of the API is still moving.
When the real API arrives, I treat the first comparison between assumption and reality as a working session, not as a verdict. We list what matched, what did not and what it costs to adjust. Most of the value is in doing that quickly and openly, while the design is still fresh in the team's mind.
Designing on assumptions is only honest if everyone can see them. Visible assumptions make the rework a shared, expected step.