How do you keep a backend compatible with old mobile app versions?

Why do old mobile app versions break when the backend changes?

Old mobile app versions break when the backend changes because, unlike a web app, you cannot replace the code on users' phones: they keep running whatever version they installed until they choose or are prompted to update.

A field you renamed or an endpoint you removed is still called by every phone that has not updated.

Store releases make this slower still. Apple's phased release, for example, takes 7 days to reach all automatic-update users, and users with automatic updates off can stay on old versions indefinitely.

What API changes are safe for old mobile app versions?

API changes are safe for old mobile app versions when they only add things: new endpoints, new optional fields in requests, and new fields in responses that old apps can ignore.

Anything that removes, renames or changes the meaning of existing data is a breaking change.

Should a small team version its API for mobile apps?

A small team should version its API for mobile apps only for the changes that have to break, and keep everything else additive.

A version in the path, such as /v2/, lets new apps use the new shape while old apps keep calling /v1/, but every version you keep is code you must test and maintain.

The cheapest strategy is the same one used for database migrations: expand first, move clients over, then contract once nobody uses the old shape. Rolling back ECS after a migration explains that pattern for schemas.

How do you know which mobile app versions are still in use?

Know which mobile app versions are still in use by having the app send its version and build number with every request, for example in a header, and logging it on the server.

That gives you a live count per version, which is the only reliable way to decide when an old version can be dropped.

• Send app version, build number and platform in a header on every request.
• Log them with each request and chart requests per version each week.
• Alert if a deploy causes errors concentrated on one app version.
• Include the version in crash and error reports, so you can tell a backend fault from an app fault.

When should you force users to update the mobile app?

Force users to update the mobile app only when an old version is unsafe or cannot work, such as a security fix or a backend change you cannot keep compatible.

Set a minimum supported version on the server, have the app check it at start-up, and show a blocking update screen only below that version.

On Android, Google Play's in-app updates offer two flows: flexible updates that download in the background while the app is used, and immediate updates, which are full-screen and require the user to update and restart. Use the immediate flow sparingly, because it stops people using the app until they update.

How do over-the-air updates affect backend compatibility with old app versions?

Over-the-air updates, such as Expo's EAS Update, shorten the tail of old JavaScript code but do not remove the problem, because they only reach builds with a matching runtime version and users who open the app.

Native changes still need a store release, and some users will stay on old builds.

Treat over-the-air updates as a way to move most users faster, not as a reason to make breaking API changes. The guide to releasing a mobile app with Expo EAS from CI covers runtime versions and release steps.

Is your backend safe for old versions of your mobile app?

Tick each item that is true today.