Interface Contract Neglect
APIs, events, and data contracts between teams degrade silently as systems evolve without formal contract management.
- Also known as
API driftthe broken handshakeimplicit contract assumptionintegration decay
- First noticed by
architectbackend engineerdelivery lead
- Mistaken for
- normal system evolution
- Often mistaken as
- an isolated bug or integration issue
Why it looks healthy
Concrete external tells that make the pattern read as responsible behavior.
- Both teams can describe the integration informally
- The integration worked the last time it was tested
- No one has filed a contract-related incident yet
- The interface looks simple from either end
Definition
What it is
Blast radius systems delivery reliability
The interfaces between systems or teams are assumed rather than specified, versioned, or tested, and they degrade over time without anyone noticing until something breaks.
How it unfolds
The arc of the pattern
-
Starts
Two teams share an interface that was initially defined informally.
-
Feels reasonable because
The contract is known to both teams, and changing it requires coordination.
-
Escalates
One team changes internal behavior. The other team's assumptions break silently or loudly. Nobody owns the contract.
-
Ends
A production incident reveals that the interface had changed, been misunderstood, or accumulated incompatible assumptions on both sides.
Recognition
Warning signs by stage
Observable signals as the pattern progresses.
EARLY
Early
- APIs are documented in a README that is not kept current.
- Interface changes are communicated verbally.
- No consumer tests exist for the contract.
MID
Mid
- Integration issues appear repeatedly at release time.
- One team is surprised by a change the other team considers minor.
- Different teams have different understandings of what the interface guarantees.
LATE
Late
- A production incident is caused by a contract mismatch.
- Debugging requires archaeology across both teams' code.
- Fear of changing interfaces causes both teams to accumulate workarounds.
Root causes
Why it happens
- Interfaces are treated as internal rather than owned
- Contract testing is seen as overhead
- Teams prioritize their own velocity over integration stability
- No single owner exists for the interface
Response
What to do
Immediate triage first, then structural fixes.
First move
Write down the current contract - exact fields, types, semantics, error shapes - and have both sides sign off before the next change.
Hard trade-off
Accept slower interface changes in exchange for changes that both sides stay compatible with.
Recovery trap
Introducing a schema registry with no enforcement, which documents drift instead of preventing it.
Immediate actions
- Document and publish the current interface contract
- Add consumer-driven contract tests
- Establish a change notification process for interface modifications
Structural fixes
- Version interfaces explicitly
- Assign interface ownership to a named person or team
- Treat breaking changes as deployments with impact assessments
What not to do
- Do not treat absence of complaints as evidence the contract is sound
- Do not allow interface changes without downstream notification
AI impact
How AI distorts this pattern
Where AI-assisted workflows accelerate, hide, or help with this failure mode.
AI can help with
- AI can help document existing contracts, generate consumer tests, and diff interface versions to surface incompatibilities.
AI can make worse by
- AI can generate new interface implementations quickly without checking compatibility with existing consumers, accelerating contract drift.
Relationships
Connected patterns
Causal flows inside Failure Modes, and related entries across the site.
Easy to confuse with
Nearby patterns and how this one differs.
-
Dependency fog is unclear what you depend on. Contract neglect is clear dependency with unclear contract shape.
-
Ownership drift is about the service owner. Contract neglect is about the contract owner - often different or missing.
- Adjacent concept Normal integration coordination
Normal coordination names a contract. Neglect lets two teams hold different versions of it in their heads.
Heard in the wild
What it sounds like
The phrase that signals the pattern is about to start, and who tends to say it.
We didn't think that change would affect anyone else.
Said byengineer explaining an incident
Notes from practice
What experienced people notice
Annotations from engineers who have worked this pattern before.
- Best momentWhen intervention actually changes the trajectory.
- When a second team begins consuming an interface for the first time
- Counter moveThe specific action that breaks the pattern.
- If two systems share a boundary, someone owns the contract.
- False positiveWhen this pattern is actually the correct call.
- Some interface changes are minor and well-communicated. The failure mode is treating all interfaces as internal details.