← Back to the library
BackendApplied · 8 min

A backend deploy breaks old app versions

“Right after a backend release, crash reports spike for app versions from months ago, or a partner's integration starts failing, while the current web client works fine.”

THE PRINCIPLE

Every field you have published is a promise to clients you cannot redeploy; extend first, remove only after usage reaches zero.

FIRST MOVES

  1. Find the break: compare request and response shapes before and after, and segment errors by app version or API client ID.
  2. Restore compatibility first (put the old field or behavior back) rather than forcing an app update.
  3. Treat removals, renames, type changes, new required request fields, and changed defaults as breaking; additions with old-behavior defaults are usually safe.
  4. Use expand/contract: add the new field alongside the old one, migrate clients, watch usage per version, then remove the old field.
  5. Run consumer-driven contract tests (for example Pact with can-i-deploy) in CI, and announce removals with Deprecation and Sunset headers plus a minimum supported app version.

TOOLS: THEN → NOW

Changing a response shape when the web client is readyAdditive changes and expand/contract, with usage tracked per client version
Provider-side schema review aloneConsumer-driven contracts (Pact) or OpenAPI diff checks that fail CI on breaking changes
Silent removalDeprecation (RFC 9745) and Sunset (RFC 8594) response headers with a published timeline

PATTERN SNAPSHOT

// Expand: serve both shapes while old clients still read "name".
function toUserResponse(user: User) {
  return {
    id: user.id,
    displayName: user.displayName, // new field
    name: user.displayName,        // deprecated: remove when usage reaches zero
  };
}

// Mark the old shape with Deprecation (RFC 9745) and Sunset (RFC 8594).
res.set("Deprecation", "@1798761600");            // 2027-01-01T00:00:00Z
res.set("Sunset", "Thu, 01 Jul 2027 00:00:00 GMT"); // not earlier than Deprecation

CLOSE THE AI. EXPLAIN THIS.

Why can adding a new enum value to a response field break an old mobile client, even though no existing field changed, and how do you design enums so it does not?

HOW IT WORKS UNDERNEATH

SOURCES

Guide reviewed