Evolving APIs for Mobile Apps and Partners: Versions, Compatibility and Retirement
Direct answer. A website can be updated whenever you like; an app already on users’ phones and a partner’s system cannot. Once an API ships, assume its callers may not upgrade for a long time. Our rules: compatible changes go into the existing version, breaking changes get a new one, the old version is marked deprecated and its usage measured per caller, it is retired only when usage allows, and the contract lives in a file that CI checks.
1.0 What counts as compatible
| Change | Compatible? |
|---|---|
| New optional request field, new response field | Yes, provided clients ignore unknown fields |
| New endpoint | Yes |
| Removing or renaming a field, changing its type | No |
| Making an optional field required | No |
| Adding an enum value | Depends on how clients handle unknown values; treat it as breaking to be safe |
| Changing error codes or default sort order | Often treated as compatible, but breaks clients that rely on them |
The last two rows are where incidents happen. From the first version, our client guidelines require a fallback display for unknown enum values instead of a crash.
2.0 Where the version goes
A path segment such as /v1/ is the most visible option and works well with logs, gateway routing and caching, so it is our default. A header looks cleaner but is easy to miss while debugging. Wherever it lives, the version only changes for a breaking change; it does not follow the product’s version number.
Within one major version the server occasionally needs small behaviour differences per client release. Have clients send their app version in a header and decide on the server, rather than creating a string of minor API versions.
3.0 The contract is a file
Describe the API in a file such as OpenAPI and keep it in the repository. CI does two things: it diffs the change against the contract of the last release and fails the build on a breaking change that is not in a new version, and it runs contract tests to check that the implementation matches the description.
For partner APIs, the contract file is the source of the developer guide, not a separately maintained document. Two documents written separately will disagree sooner or later.
4.0 Deprecation and retirement
- When a new version ships, responses from the old one carry Deprecation and Sunset headers (RFC 9745, RFC 8594), and the documentation states the retirement date.
- Measure old-version usage per caller: which app versions and which partner keys are still calling.
- For mobile, add a minimum supported version: the server publishes it, and older apps prompt users to upgrade.
- Retire only once usage is acceptably low. After retirement, return a clear error code with upgrade instructions instead of a bare 404.
The retirement date has to allow for app store review and users’ upgrade habits, and partners need time to develop, test and release on their side.
5.0 Idempotency and retries
On mobile networks retries are normal. Create endpoints accept an idempotency key: the client generates one per operation, and for a period the server returns the same result for the same key. Problems like an order submitted twice are stopped at the protocol level.
To design APIs for an app or partners, or to bring an API that has grown out of control back into shape, see Web, Cloud and Device Management, or discuss a project with us.
References
- RFC 9745, The Deprecation HTTP Response Header Field: https://www.rfc-editor.org/rfc/rfc9745
- RFC 8594, The Sunset HTTP Header Field: https://www.rfc-editor.org/rfc/rfc8594
- OpenAPI Specification: https://spec.openapis.org/oas/latest.html
Frequently asked questions
Do endpoints used only by our own web front end need this much rigour?
A web front end that ships and rolls back together with the backend can be treated more loosely, as long as the contract check still runs. As soon as one client cannot release in step with the server, such as a mobile app, a mini program or an external system, the rules in this note apply.
Does GraphQL make versioning unnecessary?
GraphQL convention is to avoid versions and evolve by adding fields and marking old ones deprecated, which is the same compatibility discipline in a different form. Before removing a field you still need to know who is querying it.
How long should an old version be kept?
There is no general answer; it depends on how fast users upgrade and on partners' release cycles. We decide from actual usage and announce the retirement date when the new version ships, so callers can plan for it.
We refactored internally. Should the public API change too?
The API describes a promise to the outside, not the internal structure. Mapping on the server and keeping the external contract stable is usually the cheapest way through an internal refactor.