Recently, one of my integration projects was closed after a difficult month of trying to bring it to life :(
The team worked hard.
We held meetings, clarified requirements, made changes, tested different scenarios, and kept trying to move the project forward. Yet despite all that effort, we could not prepare and deploy the integration in the way the business users expected it to work.
The reason was painfully simple:
We had never reached a shared agreement on what the API integration was actually supposed to do.
We had discussed systems, fields, endpoints, and technical possibilities.
People had assumptions.
People also believed that other people shared those assumptions.
They did not.
By the time the differences became visible, code had already been written, time had been spent, and every clarification created another round of changes. We were no longer refining one solution. We were trying to reconcile several different ideas of what the solution should have been.
This article is not about blaming developers, business users, or anyone else involved. It is about examining the mistake and turning it into something useful that we all as a community can lear.
So, what should we have agreed before development began?
An API Is Not Just a Technical Connection
When someone says, “We need to connect System A with System B,” the request sounds straightforward.
System A sends data. System B receives it. Done.
Except that this sentence tells us almost nothing about the behaviour the business needs.
Which event should start the exchange?
What information should be sent?
Which system owns each piece of data?… this turned out to be a major problem for our project.
Should the receiving system create a new record or update an existing one?
What happens when a mandatory value is missing?
What happens when the same request is sent twice?
What happens when one system is temporarily unavailable?
Who needs to know when the integration fails?
How will the business confirm that the data is complete and correct?
These are not minor technical details.
They are business decisions.
An API is more than a pipe between two systems. It is an agreement about how those systems will behave together. If that agreement exists only in separate conversations, assumptions, or people’s heads, the team does not yet have a requirement. It has several competing interpretations.
That was our problem.
We moved too quickly from a business idea to technical implementation.
The Most Dangerous Word in an Integration Project: “Sync”
Consider a simple requirement:
Flight data should be synchronised from System A to System B.
Everyone may nod. The sentence sounds clear. But ask five more questions and the agreement can disappear immediately.
Does “synchronised” mean:
updating every field or only selected fields?
sending changes immediately or in scheduled batches?
transferring all or only those with a particular status?
overwriting only values already changed in System B?
what if System B accepts the request but fails before completing the update?
and I could go on and on…
The original requirement did not answer any of these questions.
And yet someone will have to answer them before the integration can work.
If the business does not make those decisions, developers will make reasonable assumptions so they can continue building. QA will later test against another interpretation. And business users will assess the result against the process they imagined.
What We Should Have Done Before Writing Code
The solution is not a 100-page specification. It is a series of focused agreements, made in the right order and recorded clearly enough to build and test.
1. Start with the business outcome
Before discussing endpoints or payloads, the team should be able to answer one question:
What business outcome is this integration expected to create?
“Connect the two systems” is not an outcome. Neither is “automate the process.”
A useful outcome sounds more like this:
When a customer is approved in System A, an account must be created in System B without manual re-entry, so the operations team can begin service within ten minutes.
Now we know the trigger, the systems involved, the intended result, the user who benefits, and an important timing expectation.
At this stage, also define what is outside the scope.
If the integration creates customers but does not update them later, say so. If historical records will not be migrated, record that decision. Clear exclusions are just as valuable as clear requirements.
Output: a short initiative brief containing the objective, scope, stakeholders, consumers, constraints, and success measures.
2. Map the end-to-end business flow
An endpoint does not exist in isolation. Something happens before it is called, and something must happen after it responds.
Map the complete flow from the first business event to the final visible outcome. Include the human steps, not only the system interactions.
For each step, confirm:
who or what initiates it;
what information is required;
which system performs the action;
who owns the result;
how success becomes visible to the user;
what the user does if it fails.
This is often where hidden disagreements emerge.
One team thinks approval triggers the integration; another thinks it happens after a scheduled job. One team expects an automatic retry; another expects a person to correct the record and submit it again.
Output: an end-to-end process map with numbered steps, systems, actors, decision points, and failure paths.
3. Agree on the meaning and ownership of data
Fields with the same name do not necessarily have the same meaning.
One system’s “active customer” may mean a signed contract. In another system, it may mean that the customer has completed onboarding. A field called “STATUS” can contain technically compatible values while representing completely different business states.
Create a shared glossary and a field-level mapping. For every important value, agree on:
its business definition;
its source system;
its owner;
its format and allowed values;
whether it is mandatory;
any transformation applied during transfer;
what should happen when it is missing or invalid.
Do not allow the mapping exercise to become a purely technical comparison of column names.
The critical question is not “Can we send this field?” It is “Will the receiving system understand it in the same way?”
Output: a domain glossary and data-mapping document with ownership and transformation rules.
4. Turn expectations into explicit business rules
“Only valid customers should be transferred” is not precise enough. What makes a customer valid? Which values are required? Who approves an exception?
A testable rule might say:
A customer may be sent to System B only when the approval status is “APPROVED” and the registration number, legal name, billing country, and billing email are populated.
Now the team can implement it.
Give important rules an identifier and record the business owner who approved them. This makes later discussions much easier. Instead of debating what someone remembers from a meeting, the team can review the decision that was actually made.
Output: a lightweight business-rule catalogue.
5. Design the unhappy paths before the happy path is approved
Most teams are comfortable discussing success. A valid request is sent, the receiving system accepts it, and the record appears in the right place.
But integrations are defined by what happens when that sequence breaks.
Discuss at least these scenarios:
required data is missing;
the user is not authorised;
the same request is received more than once;
the receiving system is unavailable;
the request times out and the sender does not know whether it succeeded;
part of the transaction succeeds and part fails;
the receiving system rejects a value;
data is accepted but produces the wrong business state;
a corrected record must be submitted again.
For every meaningful failure, decide:
What response will the sending system receive?
Will the request be retried automatically?
Could a retry create a duplicate?
Will a business user see the failure?
Who is responsible for resolving it?
How can the team confirm that the final state is correct?
If QA is the first team to ask these questions, the project has already waited too long.
Output: a scenario and exception map covering success, validation failures, technical failures, retries, and recovery.
6. Write requirements that can become acceptation tests
Every requirement entering development should have a clear pass-or-fail condition.
Avoid phrases such as:
“The integration should be fast.” (a side note: I see this requirement all the time, and I still have no idea what “fast” actually means. Fast like an Arabian horse? A cheetah? A project manager five minutes before a deadline? :))
“Errors should be handled correctly.”
“The systems should remain synchronised.”
“Duplicate records should be avoided.”
They express a sensible intention, but they cannot be implemented or accepted consistently.
Instead, write the expected behaviour in observable terms:
When an approved customer is received with a registration number that already exists in System B, the API must update the existing record and return its identifier. It must not create a second customer record.
This tells the developer what to build, the tester what to verify, and the business owner what to approve.
Output: functional requirements with acceptance criteria and examples.
7. Turn the agreed behaviour into an API contract
Only now is the team ready to finalise the technical contract.
For each API endpoint, the contract should define:
its business purpose and consumer;
method, path, and version;
required headers;
request fields, formats, and validation constraints;
successful response;
error responses and their meanings;
authentication and authorisation;
duplicate and retry behaviour;
performance expectations;
logging, audit, and trace identifiers;
data sensitivity and security requirements.
OpenAPI or another machine-readable specification is extremely useful here. It creates a common reference for development, testing, documentation, and consumer teams.
But an API specification cannot invent the missing business decisions. If it is written before the rules are agreed, it is a technical draft—not yet a reliable contract.
Output: an approved API specification supported by the business rules and scenarios behind it.
8. Connect every decision to a test
A simple chain should be visible throughout the project:
Business outcome → business rule → functional requirement → API behaviour → test case
This traceability is not paperwork for its own sake.
Without traceability, every change becomes a new investigation. With it, impact analysis becomes much faster and less political.
Output: a lean traceability matrix maintained throughout delivery.
TEST: The Sentence Every Team Should Complete
Before development starts, ask the product owner, business analyst, developer, and tester to complete this sentence together:
When [business event] happens in [source system], the integration sends [specific information] to [target system]. The target system validates [rules] and then [creates/updates/rejects] the record. On success, [visible outcome] happens. On failure, [recovery and ownership] applies.
If the team cannot complete this sentence without disagreement, the integration is not ready to be built.
Did the test go well? Congratulations!
But you’re still only halfway there. Before implementation begins, run this 20-minute review to make absolutely sure everyone on the team agrees on what the integration is supposed to do.
A 20-Minute Review That Can Save Weeks
Minutes 1–5: Purpose and trigger
Confirm why the endpoint exists, who or what calls it, and which business event triggers it.
Minutes 6–10: Data and rules
Walk through the request and response. Challenge mandatory fields, allowed values, ownership, transformations, and validation rules.
Minutes 11–15: Failure and recovery
Review duplicates, timeouts, retries, partial failures, error messages, and manual intervention. Confirm who owns each recovery action.
Minutes 16–20: Acceptance
Link each important behaviour to an acceptance criterion or test. Confirm how the business will recognise that the integration works—not merely that the endpoint returned a successful status code.
5 Warning Signs That an API Project Is Not Ready
1. The requirement is only “connect the systems”
The connection is the mechanism, not the business outcome.
2. The team is designing endpoints before agreeing on rules
The structure may look correct while the behaviour remains undefined.
3. Success is documented, but failure is left for later
Error handling, retries, and recovery are part of the product—not technical cleanup.
4. Different teams use the same words without a shared glossary
Matching field names can hide conflicting meanings.
5. Business users will see the integration for the first time during acceptance testing
Acceptance testing should confirm agreed behaviour. It should not be the first moment when the expected behaviour is discovered.
Two Perspectives from the Authors
Lucia’s perspective
For me, the biggest lesson from this project is that hard work cannot compensate for a lack of agreement. I watched my team work their asses off and still get nowhere.
Next time, I would not begin by asking the team to describe the endpoint. I would bring the business owner, system owners, developer, and QA together and ask them to walk through the entire process—from the first business event to the final visible result.
I would stop whenever someone used words such as “sync,” “automatically,” “valid,” “failed,” or “updated” and ask what they meant in observable, testable behaviour. I would document the decisions, not only the discussion, and ask everyone to explain the integration back to the group in their own words.
It would require more time at the beginning. But it would save far more time, money, and frustration at the end.
Milos’s perspective
From my perspective, a reliable API is defined as much by its failures as by its successful responses.
The happy path is usually easy to describe. The real questions begin when data is missing, a request is duplicated, a system times out, or only part of a transaction succeeds. If error behaviour, retries, recovery, and ownership are not agreed in advance, the API may work technically while still failing the business.
This is especially important in regulated environments, where predictable behaviour, traceability, and auditability are essential. Documentation does not need to be extensive, but the contract must be clear enough that developers, testers, support teams, and business users all interpret it in the same way.
Our Conclusion
Good business analysis does not mean producing a library of documents that nobody reads. It means creating enough shared understanding to remove dangerous assumptions.
One clear page that answers the right questions is more valuable than fifty pages copied from a template. However, “lightweight” must never become an excuse for leaving essential decisions undocumented.
The most expensive integration problems rarely begin with bad code. They begin with reasonable people holding different interpretations of what the code is supposed to do.
Before development starts, ask everyone involved to explain what should happen before, during, and after the API call, including what happens when something goes wrong.
If their answers differ, you have found the most valuable work on the project.
And it is much cheaper to do that work today than after another month of trying to bring the wrong solution to life.
Have you worked on an integration where everyone believed they agreed—until testing proved otherwise? Share the lesson with the Analyst Harbor community. Your experience may help another analyst ask the right question before the first line of code is written.