Breaking vs Non-Breaking Changes
You'll learn: How to distinguish which API modifications will disrupt existing clients and which can be deployed safely without breaking integrations.
What Makes a Change "Breaking"?
When you modify an API, breaking changes force clients to update their code or face failures. Non-breaking changes allow existing clients to continue working without any modifications.
Think of it like changing a building's entrance: moving the front door to a different wall breaks everyone's expectations (breaking change), but adding a ramp alongside the existing stairs helps new users without disrupting current ones (non-breaking change).
Common Breaking Changes
These modifications will break existing clients:
- Removing endpoints or fields – clients requesting deleted resources get errors
- Renaming fields –
user_namebecomesusername, clients looking for the old name fail - Changing field types –
"age": "25"becomes"age": 25breaks clients expecting strings - Adding required parameters – requests missing the new mandatory field are rejected
- Stricter validation – previously accepted values now fail
- Changing HTTP status codes – clients expecting
200may not handle201properly
Common Non-Breaking Changes
These can be introduced safely:
- Adding new endpoints – existing clients ignore them
- Adding optional parameters – older requests still work
- Adding new response fields – well-behaved clients ignore unknown fields
- Relaxing validation – accepting more inputs doesn't break existing valid requests
- Fixing bugs that return correct responses
- Improving documentation or error messages
The Golden Rule
A change is non-breaking if every request that worked before continues to work afterward, returning compatible responses. When in doubt, use semantic versioning to signal breaking changes with a major version bump.
Key Takeaway: Breaking changes require clients to adapt; non-breaking changes maintain backward compatibility by only adding or expanding functionality without removing or altering existing behavior.