No breaking changes #
What Is a Breaking Change? #
As the name might suggest, a breaking change to an API is any change that can break a client’s application. Usually, breaking changes involve modifying or deleting existing parts of an API.
Examples #
Common examples of breaking changes include:
- Deleting a resource or method
- Deleting a response field
- Modifying a resource or method URI
- Modifying a field name
- Modifying required parameters
- Modifying authorization
- Modifying rate-limiting
What Isn’t a Breaking Change? #
In most cases, a change that adds to an API is not a breaking change.
Examples #
Common examples of additive, non-breaking changes include:
- Adding a resource or method
- Adding a response field
- Adding optional query parameters
How to introduce breaking changes #
- You must versionaze your APIs, example:
GET https://domain.com/v2/users - Old APIs must work correctly before and after deployment
- Coordinate timeline with stakeholders when its possible to depricate old APIs
- Add HTTP Depricate header if needed