Course contentsShow
← Software Engineering
Lesson 847 of 1,93326. API Contracts and DocumentationFree lesson

Breaking vs Non-Breaking Changes

Understand which API changes break existing clients and which can be introduced safely without disruption.

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_name becomes username, clients looking for the old name fail
  • Changing field types – "age": "25" becomes "age": 25 breaks 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 200 may not handle 201 properly

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.