Changing without breaking clients.
WHY IT MATTERS
Once something consumes your API, changing it breaks them.
WHAT COUNTS AS A BREAKING CHANGE
Removing a field Renaming a field Changing a type Making an optional input required Changing the meaning of a value Changing status codes returned
WHAT IS USUALLY SAFE
Adding an optional field to a response Adding an optional input Adding a new endpoint
WHAT TO ESTABLISH
That clients ignore unknown fields.
WHAT VERSIONING APPROACHES EXIST
A version in the address A version in a header Content negotiation
WHAT TO PREFER
Whichever your consumers handle most easily, applied consistently.
WHAT TO DO WHEN DEPRECATING
Announce it Indicate deprecation in responses Provide a migration path Set and communicate a removal date Monitor remaining usage
WHAT NOT TO DO
Remove something without notice Maintain every version indefinitely
WHAT TO DECIDE IN ADVANCE
How many versions you will support, and for how long.
