What changes about API design when your clients cannot be upgraded?
Show the full answer Hide the answer
What is being tested
Whether you understand that "deprecate in six months" means six months after the last user upgrades — which may be never.
What changes
1. Additive change only, permanently. Never remove a field an old client reads. Never change a type. Never make an optional field required. A breaking change strands users with no route to recovery, and no deployment fixes it.
2. Per-version usage instrumentation becomes essential, not nice to have. You cannot decide what is safe to change without knowing what is actually in use — and that instrumentation cannot be added retroactively to history.
3. Server-driven behaviour becomes the primary mitigation. Configuration, feature flags, and even some layout decided server-side, so behaviour can change without a release.
This matters because a bug shipped in a mobile release cannot be hot-fixed — app store review adds latency, and users choose whether to update. Server-driven configuration is the only fast path, and it must be designed in from the start.
4. Graceful handling of unknown fields, in both directions, so a newer server and an older client coexist.
5. Deprecation measured in years, with an explicit end-of-life policy for very old versions — a forced-upgrade prompt below a floor version, which is a product decision with commercial consequences.
The other constraints that shape the design
Network unreliability and cost. Batch and coalesce requests, because each radio wake-up costs battery disproportionately to the bytes transferred.
Screen-shaped APIs. One screen should be one round trip, not six — which argues for a backend for frontend aggregating close to the services.
Offline-first where the user must work without a connection. Local storage as the source of truth for the interface, with background synchronisation. This is substantially larger than caching — it introduces conflict resolution — and should be entered deliberately.
The failure to name
A breaking API change that strands old clients. It is the one mistake in this domain with no recovery, and it is why the additive-only discipline is not negotiable.