Replacing a System Without Switching It Off
7 parts, in reading order.
Replacing a System Without Switching It Off, Part 1: Plan the Cutover in the Design
The decisions that make a rollout safe are made long before the first site goes live. A phased replacement needs these in the design: phasing by client then site, events that are stored before they're sent, old and new APIs side by side, configuration per client, and a settle period.
Replacing a System Without Switching It Off, Part 2: Version One Endpoint, Not the Whole API
When clients can't all update at once, version only what changed and run it next to the old one. In code that's a v2 folder with one controller, a rule that published versions never change, and the question of when the old one goes.
Replacing a System Without Switching It Off, Part 3: Client Differences as Configuration, Not Code
A new jurisdiction or rule should be data, not a release. But once the differences between clients live in configuration, that configuration needs the same care as code: review, versioning and rollback. What goes in it, and the point where it turns into a programming language.
Replacing a System Without Switching It Off, Part 4: A Read Model for Devices
A device-facing API can keep its own view of the data, built from events, instead of fanning out to a dozen services for every screen. What the device needs to see, how the view is built, why reads stay local and writes are forwarded, and what eventual consistency costs.
Replacing a System Without Switching It Off, Part 5: Living With a Mixed Estate
The expensive part of a phased rollout isn't the code, it's running two worlds at once. Support, training, reports and integrations all have to cope with some sites on the old system and some on the new. What that costs, how long is too long, and what I'd plan differently.
Replacing a System Without Switching It Off, Part 6: Retiring v1, Decide the Date When You Create v2
Old API versions live for ever unless their end is planned from the start. Find out who still calls v1, pick a date once traffic drops, chase the stragglers and finally delete the code, using the mobile app API from Part 2 as the example.
Replacing a System Without Switching It Off, Part 7: The Async Side Was Fine, Where Our Microservices Actually Broke
After about three years on a case-management platform for the justice sector, a look back at what held up, what didn't, and the question I'd ask first next time: how does each dependency fail? Most distributed systems handle the happy path by design and the failure path by accident.