Interfaces Outlive Implementations

What a system exposes to the outside lasts longer than what works on the inside. This story is about a moment when that difference suddenly mattered. It is deliberately kept general — no provider, no client, no date.

Situation

An external API provider that a system was built on was being replaced. Over time, millions of existing records had accumulated that followed the old provider. The new provider offered the same capability, but in a different structure that was incompatible with the old one. The task was to replace one with the other without losing the existing data.

Initial assumptions

The obvious view was that switching providers is mainly a matter of wiring: you swap the source and call the new one instead of the old. The effort seemed to lie in the cutover. That the millions of already stored records carried the real weight only came to the fore once the incompatibility of the structures became visible.

Problem

The new structure did not map onto the old one. Every existing field, every meaning had to be mapped to its counterpart in the new model — and where there was no clean counterpart, a decision had to be made. With millions of records, such a mapping is not a one-off task but a process whose completeness and correctness you have to prove. The problem was not the cutover; it was translating a large body of data from one language into another without loss.

Root cause

The deeper cause was a confusion that is easy to fall into: equating the interface with the provider behind it. The provider is the implementation — replaceable, transient. The interface and the data that flowed through it and stayed are what lasts. A system that had not separated its own view of the data from the incidental shape of a provider felt the switch all the way down into its stored data.

Decision

The decision was to bring the data into a form of its own, independent of the provider, and to connect the new provider behind it — treating the interface as what stays and the implementation as what can be swapped. It is not the provider that determines the shape of the data, but the system.

Implementation

The old data was mapped onto the new model — meaning by meaning, not field by field out of habit. The migration ran in verifiable steps, and each step was checked: does the translated data match the original? Only once the check held was a part considered migrated. Mapping, migration and verification were three separate, deliberate pieces of work — not a hasty cutover.

Trade-offs

Decoupling the data from the provider and translating a large body of data with verification costs considerably more than a direct cutover. You build a translation layer and verify millions of records instead of simply swapping the source. The price buys independence from the next provider switch and the certainty of having lost nothing. We would handle it differently only for a small, non-critical dataset whose loss would be bearable and which would be cheap to obtain again.

What we learned

Interfaces outlive implementations. The provider behind an interface is replaceable; the data that flowed through it and stayed is not. Anyone who ties their view of the data to the shape of a specific provider makes the transient the foundation of the lasting — and pays for it at the first switch. Having your own, independent shape for the data is not a nice-to-have but the safeguard against someone else's decision shaking your own data.

How this changed Batunet

Since then, we deliberately distinguish between the interface that stays and the implementation that goes. We bring data into a shape that belongs to the system, not to the provider — and treat every external service as something that will be replaced one day. Switching providers is therefore no longer an earthquake but a planned operation behind a boundary that holds.

Further reading

• Guide: API Design for Long-Lived Systems — why the contract surface is the longest-lived part and why you should be free to change the inside.
• Guide: API Versioning Without Breaking Clients — evolving interfaces without harming existing data and consumers.
• Guide: Zero-Downtime Database Migrations — migrating large datasets in a verified, reversible way.
• Guide: Software That Still Runs in Ten Years — why the lasting and the transient need to be separated.

The foundation is the Batunet Engineering Method: separate the lasting from the swappable, migrate in verifiable steps, prove completeness.

A provider is borrowed; the data that flowed through it stays. Confuse the two, and you build what should last on something transient.