API Breaking Change Policy
Less than to read
Sage People is constantly evolving, and the Sage People APIs will naturally evolve alongside it. For the most part, changes will be enhancements and additions, but sometimes it will be necessary to change behavior or even remove functionality. Changes can be split into two broad categories: breaking and non-breaking.
Breaking Changes
As the term implies, a breaking change to a piece of functionality may cause an error or change behaviour in a consuming application. When moving to a later major version of the API, developers must therefore take care to ensure that their application is functioning correctly.
Some examples of breaking changes are:
- Changes to the intended functionality of an endpoint
- Removing or renaming the URL of an endpoint
- Removing, renaming or changing the type of a field in the response
- Adding a new or changing an existing validation to an existing resource
- Requiring a query parameter on an endpoint that wasn’t required before
- Adding a required header to an existing endpoint
- Changing existing error response codes
- Adding a new error category code (defined as ErrorCategory in our API reference)
When we release a new major version of Sage People APIs, it contains at least one breaking change, but it is likely the breaking changes only affect a small part of Sage People APIs. To assist integrators in determining the scope of any changes necessary to their integration, Sage People will provide details of the breaking changes in the release notes.
Non Breaking Changes
A non-breaking change is a change that you can adapt to at your own discretion and pace without disruption to existing functionality.
Some examples of non breaking changes are:
- New endpoint
- New methods to existing endpoints
- New fields in the response
- Changes to error messages
- Changing the order of the fields in the response
- Adding a new inner error code (defined as ErrorCode in our API reference)