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.

Diagram of an API version lifecycle. /v1 is live and receives only additive changes; a breaking change opens /v2; /v1 is then marked deprecated with Deprecation and Sunset headers and is finally removed with a clear error. Below: usage tracking on /v1 per app version and partner key, with removal only when usage allows; and a contract file (OpenAPI) diffed against the last release in CI, where a breaking change outside a new version fails.
Figure 1. A major version from live to deprecated to removed. Retirement follows usage, not the calendar.

1.0 What counts as compatible

ChangeCompatible?
New optional request field, new response fieldYes, provided clients ignore unknown fields
New endpointYes
Removing or renaming a field, changing its typeNo
Making an optional field requiredNo
Adding an enum valueDepends on how clients handle unknown values; treat it as breaking to be safe
Changing error codes or default sort orderOften 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

  1. 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.
  2. Measure old-version usage per caller: which app versions and which partner keys are still calling.
  3. For mobile, add a minimum supported version: the server publishes it, and older apps prompt users to upgrade.
  4. 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

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.