API Backwards Compatibility

Also Known As

TL;DR

Explanation

Safe (backwards-compatible) changes: adding optional fields, adding new endpoints, adding optional query parameters, adding new enum values (with caution — clients must handle unknown values). Breaking changes: removing fields, renaming fields, changing field types, changing response structure, removing endpoints, making optional fields required. Breaking changes require a new API version. Semantic versioning applies: v1 → v2 for breaking changes. Deprecation policy: announce → deprecate (with Deprecation header) → sunset date → remove.

Diagram

flowchart TD
    subgraph Safe Changes - No Version Bump
        A1[Add optional field to response]
        A2[Add new endpoint]
        A3[Add optional query param]
    end
    subgraph Breaking Changes - Requires v2
        B1[Remove or rename field]
        B2[Change field type]
        B3[Make optional field required]
    end
    subgraph Deprecation Flow
        CURR[Current field] -->|add new| BOTH[Both fields returned]
        BOTH -->|Deprecation header + sunset date| DEP[Old field removed in v2]
    end
    style A1 fill:#238636,color:#fff
    style A2 fill:#238636,color:#fff
    style A3 fill:#238636,color:#fff
    style B1 fill:#f85149,color:#fff
    style B2 fill:#f85149,color:#fff
    style B3 fill:#f85149,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Removing or renaming fields without a versioning strategy — all existing clients break silently.
• Adding required fields to a request body — existing clients don't send the field, their requests fail.
• Changing a field from nullable to non-nullable — clients handling null will fail if the type changes.
• No deprecation header or sunset date — clients have no warning before a field disappears.

Avoid When

• Internal APIs consumed only by your own team — strict backwards compatibility slows iteration unnecessarily.
• Early-stage APIs still being designed — lock the contract too early and you constrain good design decisions.
• Maintaining compatibility for zero consumers — prune unused versions rather than preserving them.

When To Use

• Public APIs with external consumers who cannot be forced to upgrade on your schedule.
• Mobile app APIs where old versions remain in the field for months or years.
• Any API covered by an SLA or partner contract that guarantees stability.
• After the API has been in production — any change to an existing field is a breaking change.

Code Examples

// v1 API response:
{ "user_name": "alice", "user_email": "alice@example.com" }

// 'Refactor' renames fields without versioning:
{ "name": "alice", "email": "alice@example.com" }
// All clients reading user_name now get undefined/null
// No errors thrown — silent breakage in production

// Additive transition — both names during migration:
{
    "name": "alice",         // New field
    "user_name": "alice",    // Kept for backwards compat (deprecated)
    "email": "alice@example.com",
    "user_email": "alice@example.com" // Kept (deprecated)
}
// Deprecation header:
// Deprecation: Sat, 01 Jan 2027 00:00:00 GMT
// Link: https://api.example.com/docs/migration; rel="deprecation"

// After sunset: bump to v2 which removes old fields

References

• ↗ https://www.mnot.net/blog/2021/10/12/deprecation

Tags

Related Terms