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.emailwill crash if it disappears - Changing data types: Switching
agefrom integer to string breaks parsing logic - Renaming fields:
firstNamebecomingfirst_namesevers 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.