Course contentsShow
← System Design
Lesson 1905 of 1,91945. API Design and VersioningFree lesson

Breaking vs Non-Breaking Changes

Identifying which changes require new versions: removing fields, changing types, vs adding optional fields.

Breaking vs Non-Breaking Changes

What you'll learn: How to distinguish between API changes that force clients to upgrade (breaking) versus those that maintain backward compatibility (non-breaking).

The Core Distinction

When evolving an API, every modification falls into one of two categories. Breaking changes force existing clients to update their code or face errors. Non-breaking changes allow old clients to continue functioning without modification while new clients can adopt enhancements.

Think of it like a conversation: changing the meaning of words someone already knows is disruptive (breaking), but introducing new optional topics they can choose to discuss is seamless (non-breaking).

Breaking Changes That Require New Versions

These modifications violate the contract with existing clients:

  • Removing fields from responses: Clients expecting user.email will crash if it disappears
  • Changing data types: Switching age from integer to string breaks parsing logic
  • Renaming fields: firstName becoming first_name severs existing references
  • Making optional fields required: Requests missing the now-mandatory field get rejected
  • Removing or renaming endpoints: Old URLs return 404 errors

Non-Breaking Changes (Backward Compatible)

These keep existing clients happy:

  • Adding optional fields to requests: Old clients omit them; new clients can include them
  • Adding new fields to responses: Old clients ignore unknown properties
  • Adding new endpoints: Existing routes continue unchanged
  • Making required fields optional: Relaxing requirements never breaks callers
  • Expanding enums: Adding new status values (if clients handle unknowns gracefully)

The Version Decision

Breaking changes demand a new major version (v1 → v2). Non-breaking changes can live within the same version, perhaps incrementing a minor version for tracking (v1.0 → v1.1).

Key Takeaway: Only introduce new API versions for breaking changes—those that alter or remove existing contracts. Additions and relaxations should be backward-compatible to minimize client disruption.