How Do You Keep Older App Versions Working?
Mobile app API backward compatibility means an older supported app can still complete its intended tasks after the backend changes. Preserve the requests it sends, the responses it understands and the meaning of existing fields. Prefer additive changes, test each supported contract, and identify clients that depend on old behaviour before removing it.
What should remain compatible?
Define compatibility around user tasks: signing in, loading saved records, submitting changes and understanding failures. A response that arrives successfully but causes the app to show the wrong result should fail your compatibility checks.
For each supported app release, record the requests it sends and the response shapes it expects. Include required fields, allowed values, error responses and pagination rules. Also record behaviour that matters to users, such as whether repeating a submission creates another record.
Use this record to review backend changes. If a proposed change alters an existing expectation, either preserve the old behaviour or introduce a separate contract for the new app. Eventually you may also decide when to stop supporting older Android versions.
Our guide to what app maintenance involves after launch explains where ongoing support fits after the initial release.
Which API changes should you prefer?
Prefer adding a new capability while keeping the existing one available. Treat “additive” as a design choice to verify, rather than automatic permission to release.
| Proposed change | Compatibility check |
|---|---|
| Add a response field | Does every supported client tolerate the extra field? |
| Add an optional request field | Does omitting it preserve the previous behaviour? |
| Rename or remove a field | Can the old name remain available during migration? |
| Change a field's type | Can a new field carry the new representation? |
| Add a status value | What will an older app display or allow? |
| Change an error response | Can the older app still explain the failure? |
Adding a response field is not universally safe: a client using strict response validation may reject an unknown field.
Do not reuse an existing field for a different meaning. Keep a delivery estimate separate from a confirmed delivery time, for example. Even if both use the same data type, your compatibility review should treat their meanings as different.
How should optional fields behave?
Write down what happens when a field is missing, explicitly empty or set to null. Do not leave those cases to accidental implementation behaviour.
For a new request field, choose a default that preserves the existing task when an older app omits it. If omission cannot be handled safely, introduce the capability through a separate contract rather than making the new field compulsory for every client.
For a response field, define the app's fallback. A missing delivery note might mean hiding that section. It should not mean preventing the user from opening the order.
Apply the same discipline to updates. Specify whether an omitted field means “leave unchanged” and whether an explicit empty value means “clear this value”. Test those cases separately.
Keep defaults visible in the contract description so both app and backend changes can be checked against the same rule.
What does a compatible change look like?
Consider an illustrative order screen. Its existing response contains an order reference and a status. A new app design needs a short delivery note.
A compatible rollout would aim to:
- Keep the existing order reference and status unchanged.
- Add the delivery note as an optional response field.
- Verify that supported older apps accept the response.
- Make the new app handle an absent note.
- Preserve the previous behaviour when an older app updates an order without sending the new field.
Now suppose the new design also introduces a status meaning “partially fulfilled”. Do not approve that change solely because it adds a value. Inspect how each supported app handles an unfamiliar status.
One design option is to retain a meaningful, established status in the old contract and expose the richer state separately. Use that option only if the old representation remains truthful and the actions offered by the older app remain valid. Otherwise, introduce a separate contract and plan the transition.
What should contract tests prove?
Contract tests should check whether the backend still meets the expectations of supported clients. Start with representative requests and assertions about the responses those clients require.
For each supported contract, include:
- A request containing only the fields the older app sends.
- Assertions for required response fields, types and meanings.
- Missing, empty and null values where the contract permits them.
- Unknown response fields and unfamiliar status values.
- Error responses the app must translate into useful messages.
- Pagination and repeated submissions where those affect the task.
Make tests capable of detecting a break. Temporarily remove a required response field or change its type and confirm that the relevant check fails. A test that checks only for a successful response does not prove that the expected fields are present.
Keep a separate check using the actual older app against the proposed backend. Cover the important journeys, including reading existing records and saving changes. Our Android app testing guide provides a broader release-testing checklist.
How do you identify incompatible clients?
Before announcing removal, build a view of which clients use the affected contract.
Where available, record the app version, build identifier, platform and API contract alongside requests. Include an explicit “unknown” category when identification is missing. Do not interpret an unidentified client as a current client.
Then ask a narrower question than “How many people use an old app?” Identify which clients still call the operation you intend to change, and whether those calls succeed.
Use a release decision checklist:
- Which app builds depend on the old behaviour?
- Which affected clients have made recent requests?
- Are background operations or integrations using the same contract?
- What will happen when a long-absent user returns?
- Can an affected user update and then resume the task?
Recent request records alone cannot show that an installed app will never return: an app left unused during the period you checked leaves no record.
Use activity as evidence for the decision, alongside an explicit policy for returning users.
How long should the deprecation window be?
Choose the window around the consequences of losing access. Define what remains supported, how users will hear about the change and what happens after support ends.
Avoid treating a fixed duration as sufficient evidence by itself. Before closing the window, check affected usage, unresolved compatibility failures and the availability of a working update.
Give users a clear message: what needs updating, which action will become unavailable and how to continue. If they have unsent work, include a way to preserve or recover it in the transition plan.
Make removal a separate decision from launching the replacement. Keep a recovery plan for the old contract until the agreed removal checks pass.
What common mistakes should you avoid?
Assuming everyone updates promptly. Build the support policy around older versions remaining in use.
Testing only the newest app. Include the oldest supported contract and any intermediate release with different expectations.
Calling every new field harmless. Verify parsing, defaults and unfamiliar values against supported clients.
Changing meaning without changing shape. Review units, status meanings and available actions as carefully as field names.
Using a forced update without a recovery path. Decide what happens to unsent work and interrupted tasks before blocking access.
Removing support because traffic looks quiet. Account for unidentified clients and returning users before approving removal.
Frequently asked questions
Do you need a new API version for every change?
Use a separate version when you cannot preserve an existing contract's meaning or behaviour. For an additive change, first verify that supported clients accept it and that omission preserves previous behaviour.
Must every old app remain supported forever?
Set a clear support policy with a defined transition path. Review it against actual dependencies and the consequences for affected users before ending support.
Should app version determine access?
Use version information to identify compatibility needs and guide updates. Keep permission checks separate: the backend should decide access using the user's authenticated permissions.
When is it reasonable to require an update?
Consider it when the older app can no longer complete the task safely or correctly. Provide a clear explanation, a usable update route and a plan for unfinished work before enforcing the requirement. Our guide on when to force a mobile app update covers that decision in more detail.