Putting one clean API in front of a decade of legacy

I once joined a project where the new mobile team was completely blocked. Their goal was a modern customer app, but the backend was a mess of a dozen services built over fifteen years. There were SOAP endpoints, mainframe FTP drops, and a critical Oracle database everyone queried directly. The first suggestion from management was the one I always hear: "Let's just rebuild it all." It’s a tempting fantasy of a clean slate, but it is almost always the wrong move.

This discipline of creating clean contracts over chaos is the bedrock for everything that comes next. You cannot build reliable AI agents or deterministic data pipelines on top of a shaky, undefined foundation.

The Fallacy of the Big Rewrite

A full rewrite sounds like a technical solution, but it’s a business problem. The business cannot afford to freeze product development for two years. The risk is immense. I've seen these projects burn their sponsor's credibility when, a year in, they can only show a mounting cloud bill for a staging environment, not a single new feature. The core mistake is believing the challenge is writing new code. It's not. The real challenge is migrating a decade of accumulated state and implicit business logic without shutting everything down.

Your First Defense: The Facade API

The pragmatic first step is to establish a single, clean boundary between the legacy chaos and any new development. This boundary is an API that serves as a Facade. It’s more than a simple proxy; it's an active translator. In the language of Domain-Driven Design, this is an Anti-Corruption Layer. Its job is to protect the sanity of your new applications from the quirks of the old ones.

This API Facade speaks a modern, well-structured language to the outside world. Internally, it orchestrates the ugly sequence of calls needed to fulfill one clean request. A single call to GET /api/v1/customer/{id} might trigger three internal calls: one to a SOAP service, a direct SQL query, and a file scrape. The key is that the client knows nothing of this. You have established a stable contract that you can honor while changing everything behind the curtain.

Strangling the Monolith, One Endpoint at a Time

With the facade in place, you can apply what Martin Fowler named the Strangler Fig Application pattern. The pattern is named for a vine that slowly grows around a host tree, eventually replacing it. Our API Facade is the root of that vine.

Take a user profile endpoint. Initially, /api/v1/profile in the facade reads from the old user table. Later, you deploy a new profile microservice. You then change the facade's logic: any PUT request now writes to both the new service and the old database. This sync phase populates the new system. For reads, you can slowly shift traffic to the new service, verifying the results. Once confident, all traffic goes to the new service, and you eventually cut the write to the old system. You have strangled one piece of the monolith. Repeat this, domain by domain.

The Real Costs and Trade-offs

This approach is powerful, but it introduces its own complexity. The facade adds a network hop, so aggressive caching is a requirement, not an option. You must measure the performance impact of every translation.

You also often lose transactional integrity across systems. This forces you to design for eventual consistency, implementing robust retry mechanisms and compensation logic. For complex, multi-step operations, this might require a pattern like Sagas, as described in the original 1987 paper by Garcia-Molina and Salem. This can be a difficult shift for teams accustomed to monolithic ACID guarantees.

While this facade-first approach is often the most pragmatic start, it’s not the only way. Event-driven strangulation, using Change Data Capture (CDC) from a legacy database, offers better decoupling but introduces significant operational complexity in managing event ordering and idempotency. The API facade is simpler to start and keeps the focus on the business contract, which is why I often begin there.

A Blueprint for Moving Forward

Despite the challenges, this is the most reliable pattern I have used to tame old systems without derailing the business. The path forward is disciplined and incremental.

• Define Your Seams. Don't just proxy everything. Find logical business domain boundaries. This is where you will wrap your strangler fig.
• Obsess Over the Contract. Your API contract is the one stable element. Design it from the outside in, based on what the business needs, not what the legacy systems provide.
• Be a Ruthless Translator. Do not allow legacy data structures or naming conventions to leak into your new API. The facade's job is to be an anti-corruption layer. It protects the new world from the old.
• Strangle, Don't Explode. Pick one, high-value vertical slice of functionality. Move it behind the facade and migrate it fully. Demonstrate success, build trust, and then move to the next.

This isn't a quick fix; it's a multi-year strategy. But unlike the big rewrite, it delivers value from day one, it contains risk at every step, and it actually has a high chance of working.