API modernization is sold as a protocol exercise - SOAP to REST, XML to JSON, ESB to something lighter. The protocol conversion is the small part. The cost and the risk both come from the consumers: how many there are, whether you know who they are, and how many of them you control. A modernization priced on endpoint count and delivered against consumer count is a programme that overruns.
01Start by counting consumers, not endpoints
An integration layer with forty endpoints and three internal consumers is a short project. The same forty endpoints with sixty consumers, a third of them external partners on contractual notice periods, is a multi-year programme where the engineering is not the constraint.
The first deliverable of any API modernization should therefore be a consumer inventory built from traffic data rather than from documentation. Documentation reflects what was intended; access logs reflect what is actually called, and the gap between them is where the unpleasant surprises live.
02The facade buys you sequencing
Putting a modern API in front of the legacy integration layer lets new consumers integrate against the contract you want while existing ones stay put. That single move stops the problem growing, which matters more than it sounds - most integration layers are hard to retire because they kept accumulating dependencies throughout the modernization programme.
The facade must stay thin. Its job is protocol translation, shape normalisation and sensible timeout and retry behaviour. Once business rules move into it, you have built the next system to modernize, and it will be harder than the one it replaced because nobody will consider it legacy.
03What drives the cost
Three things dominate. First, consumers you do not control, because their migration runs on their release schedule and their commercial incentives. Second, undocumented behaviour that consumers depend on - the field that is always null except in one case, the endpoint that returns a different shape on error. Third, contract testing, which is what stops the migration silently breaking a consumer nobody thought to check.
Protocol conversion itself is largely mechanical and is rarely where the budget goes. When a proposal is priced primarily on endpoint count, it has almost certainly not accounted for the other three.
| Driver | Impact | How to bound it |
|---|---|---|
| External consumers | High - runs on their schedule | Contractual notice, long dual-run period |
| Undocumented behaviour | High - found late, by breaking something | Shadow traffic comparison before cutover |
| Contract test coverage | Medium - upfront cost, prevents incidents | Generate from recorded production traffic |
| Protocol translation | Low - mechanical | Standard tooling; rarely the constraint |
| Auth model change | Medium to high | Migrate auth separately from protocol, never together |
04Run both and compare before you switch
The safe cutover is not a cutover. Route a copy of production traffic to the new implementation, compare responses against the legacy path, and fix every difference before moving a single real consumer. Differences will be found, and most will be behaviour nobody knew was there.
Only once shadow comparison is clean does traffic move, and it moves per-consumer with the ability to route back within seconds. A migration that has never run in shadow is not ready, whatever the test suite says - the test suite encodes what was understood, and the whole problem is what was not.
- Build the consumer inventory from access logs, not from documentation
- Stand up the facade early so new integrations stop landing on the legacy path
- Shadow-compare until differences are zero or explicitly accepted
- Migrate per consumer, with instant rollback, never in one window
- Delete the legacy path only when traffic is provably zero, not when migration is 'complete'
Topics
Marcus Hale
Lead Architect · SyncTrix
Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.
Building something like this?
SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.