Mobile clients live for years with versions you cannot patch, which makes API versioning a long-term compatibility contract rather than a naming scheme. In 2026 the settled best practice for most teams: additive evolution with tolerant clients, plus explicit sunset windows for the rare breaking change.
Additive changes beat versions
The cheapest evolution is adding fields and endpoints while tolerating unknown ones on input. Teams that design for forward compatibility rarely need a v2, because most changes never had to break anyone.
When to actually version
Reserve explicit versions for semantic changes you cannot make compatible: auth model shifts, resource restructuring, or corrected behavior. Versioning everything creates parallel maintenance that slows every subsequent change.
Sunset with data
Deprecation works when you can see who still calls the old surface. Usage data per client turns a feared breaking change into a targeted migration conversation with a deadline everyone can plan around.
Additive by default
The cheapest versioning strategy is one that never versions: add fields rather than changing them, introduce new endpoints rather than repurposing old ones, and let clients ignore what they do not understand. Version-in-media headers or URLs exist for the cases where semantics genuinely must change — and those should be rare enough to count. The discipline required is server-side restraint: no "harmless" renames, no repurposed fields, no changed nullability.
Sunsets, deprecation windows and telemetry
When a break is unavoidable, the sequence is measurable: announce with a timeline, instrument server-side usage by client version so you know who is affected, provide a migration path with parallel run periods, then enforce. Usage telemetry turns deprecation from guesswork into a checklist — you cannot sunset what you have not measured. For mobile specifically, align API sunsets with app-store update adoption curves; a forced break at 70% adoption leaves a real population stranded.
Key takeaways
- Add fields, never change them — most APIs should rarely version.
- Instrument client-version usage before promising any sunset.
- Align deprecation windows with mobile adoption curves.
Final thoughts
API versioning is a promise to clients who cannot be forced to update, and the teams that keep it simple — additive evolution plus measured sunsets — spend their engineering on features instead of compatibility shims.