The backend team renames a field in an API response, updates the web dashboard, the tests pass, and the deployment takes five minutes. The next day Crashlytics shows a wave of crashes and the store fills with one-star reviews. The culprit is a year-old version of the mobile app that some users never updated.
This is one of the most common problems companies maintaining apps come to us with. Below we explain why a mobile app needs a different approach to API changes than a website, which changes break old versions, and how to evolve the backend without leaving users with an app that doesn't work.
Why a mobile app is a different client than a website
Web app Mobile app Version the user has Always the latest after a page refresh Whatever they installed — sometimes years ago Time to ship a fix Minutes From a few hours to a few days (store review, staged rollout) Rolling back a bad version Immediate Impossible for those who already downloaded it Control over updates Full None, unless the app has a forced update mechanismThen there's staged rollout: on Google Play a new version is usually released by percentage, and on the App Store a phased release spreads over seven days. Even in the best case, at least two app versions run side by side for many days — in practice, more than a dozen.
The takeaway: a mobile app's backend has to serve not one client, but every app version that's still in use.
Which API changes break old app versions
Not every API change is dangerous. The problem is that some changes that look safe do break apps — depending on how response parsing was written.
API change Risk for an old version Removing or renaming a field High — missing data or a crash Changing a field's type (e.g. number to string) High — the whole response fails to parsenull in a field that always had a value before
High, especially in Kotlin and Swift with non-nullable types
A new value in an enum field (e.g. a new order status)
High with the default configuration of many libraries
A new required request parameter
High — the old version won't send it
Changing date, currency, error code, or HTTP status formats
Medium to high
Changing pagination or sorting
Medium — wrong or incomplete lists
Adding a new optional field to a response
Usually low — but not always
Adding a new endpoint
None
Two examples we regularly see in projects we take over:
- Unknown fields. The kotlinx.serialization library, in its default configuration, throws an error when a response contains a field the app's class doesn't know. All it takes is the backend adding a new field, and the old Android version stops loading the screen. The fix is setting
ignoreUnknownKeys = true— but only in new versions; old ones stay as they are. - Unknown enum values. Swift's
Codableand the codejson_serializablegenerates by default in Flutter throw an error when an enum field receives a value outside the list. A new order status added on the backend can disable the order history screen in every older app version.
So before you consider a change safe, check how the oldest app version that still has users parses responses.
The rule: extend, don't change
Most changes can be made without API versioning, using the "expand and contract" model:
- Expand. Add the new field next to the old one. The backend fills both; old app versions keep using the old one.
- Migrate. Ship an app version that uses the new field.
- Wait for the data. Watch how many requests still come from old versions. We described where to get these numbers in the article on mobile app analytics.
- Contract. When the share of old versions drops to an acceptable level — or after you raise the minimum supported version — remove the old field.
This process takes weeks or months, not hours. That's normal. The cost of keeping two fields for a quarter is negligible compared with the cost of a crash for some of your users.
API versioning — when you need it
When a change is too big to make by expanding — a new data model, a different authorisation method, a rebuilt process — you need a new API version.
Approach Pros Cons Version in the path (/v1/orders, /v2/orders)
Clear, easy to monitor and route
Temptation to copy the whole API for every change
Version in a header
Clean URLs, version per request
Harder debugging and caching
Branching on app version
No URL changes
Conditional logic scattered across the backend, hard to remove
For most apps we maintain, a combination works: expanding for everyday changes and a path version for major rebuilds. It's also worth adopting a rule that at most two API versions run in parallel, and the older one has a shutdown date set in advance. Every extra version is code that has to be tested, secured, and updated — we cover what an unattended backend costs in the article on mobile app backend maintenance.
The app has to say which version it is
All of the techniques above require one thing: the backend has to know which app version sent the request. The simplest way is a fixed header with the version and platform, e.g. X-App-Version: 4.2.1 and X-Platform: ios, sent with every request.
This way:
- logs show how much traffic each version generates,
- the backend can, in exceptional cases, respond differently to an older version,
- you can safely decide when to remove an old field or shut down an old API version.
The second element is a minimum supported version mechanism — an endpoint or remote config that lets you force an update when maintaining compatibility no longer makes sense. We described it in detail in the article on forcing app updates. Both mechanisms have to be added in advance: you can't teach a version that's already on phones to send a header.
A defensive client: how to write an app that survives changes
Part of the resilience lies on the app side. In new versions, make sure the app:
- ignores unknown fields in responses,
- has a default for unknown enum values (e.g.
unknown) and displays them neutrally instead of throwing an error, - treats missing optional data as a normal state, not an exception,
- handles agreed response codes — e.g.
410 Gonefor a retired endpoint — with a message asking the user to update instead of a blank screen, - doesn't call third-party APIs directly if it can go through your own backend. When a maps, payments, or login provider retires an old API version, a server-side fix reaches all users at once. We describe how often this happens in the article on deprecated SDKs and APIs.
Compatibility tests
Manually checking every change against several old app versions doesn't scale. It's better to automate it on the backend side:
- recorded requests and responses from old versions — a set of examples that run through the new backend on every change and are compared with the expected format,
- contract tests (e.g. Pact) — the app declares what it expects from the API, and the backend can't be deployed if it breaks the contract of any supported version,
- a test on a real old version before bigger changes — installing the latest store versions on a test device and walking through the key flows.
If the app has no tests at all today, we described where to start in the article on testing an old mobile app.
The most common mistakes
- Deploying API changes with only the web app or the latest mobile version in mind.
- No app version information in requests — decisions to remove fields are made blind.
- A new API version for every change, with no shutdown date for the previous ones.
- Removing an old field right after shipping a new app version, before users install it.
- Calling third-party APIs directly from the app, which can't be fixed without an update.
- No forced update mechanism — the only way out of an incompatibility is keeping the old API forever.
How much does it cost
Adding an app version header, a minimum version mechanism, defensive parsing in the app, and basic compatibility tests for key endpoints usually takes 24–60 hours of work on the app and backend side. At an example rate of PLN 180 net per hour, that's roughly PLN 4.3k–10.8k net. The rate and scope are indicative — they depend on the number of endpoints and the state of the code.
For comparison: a single incompatible API change that disables a key screen in older versions usually means a few days of firefighting, an urgent release, and a drop in store ratings that takes months to recover.
Summary
A mobile app is a client you can't update on demand. The backend has to serve every version that's still in use. Most changes can be made by expanding the API: a new field next to the old one, a new app version, and removing the old field only after checking the data. Keep versioning for major rebuilds and limit it to two parallel versions. The foundation is an app that sends its version, has a minimum supported version mechanism, and doesn't crash on unknown data.
We design and maintain backends for mobile apps as part of our backend and API service, and keep apps compatible with server-side changes as part of mobile app maintenance. If you want to check how your app will cope with API changes, request a free app analysis or get in touch.