Changing without breaking callers.
WHAT COUNTS AS A BREAKING CHANGE
Removing a field or endpoint Renaming anything Changing a type Making an optional parameter required Changing error behaviour Changing the meaning of a value
WHAT IS SAFE
Adding optional fields Adding endpoints Adding new values a caller can ignore
WHAT THE VERSIONING APPROACHES ARE
A version in the path A version in a header A date-based version No versioning, with additive changes only
WHAT THE PATH APPROACH PROVIDES
Visibility, and simple routing.
WHAT IT COSTS
Version sprawl, and callers pinned to old behaviour indefinitely.
WHAT THE ADDITIVE APPROACH PROVIDES
No versions to maintain.
WHAT IT REQUIRES
Discipline, permanently.
WHAT TO DECIDE BEFORE PUBLISHING ANYTHING
Your approach.
WHY BEFORE
Retrofitting versioning is painful.
WHAT TO NEVER DO
Change behaviour within a version silently.
WHY
Callers cannot detect it, and their systems break unpredictably.
WHAT TO COMMUNICATE
Every change, in a changelog with dates.
WHAT TO PROVIDE WHEN RETIRING A VERSION
Long notice A migration guide Visibility of who is still using it
