Breaking Change Policy
Learn about how we version our APIs to ensure your integration is robust.
Breaking Changes Policy
We aim to avoid releasing API changes that will cause any request that was previously successful to become unsuccessful or alter any response in a way that is likely to break a client implementation, except in the cases described below.
What changes do we consider non-breaking?
- Add properties to a response
- Add optional properties to a request
- Add optional headers to a request
- Add new endpoints
- Add new request methods to existing endpoints
- Add additional response headers
- Support values in properties and headers that would previously have been rejected
- Change the order of properties or array elements in a response, unless the order is explicitly specified
- Change documentation
- Make what would otherwise be a breaking change that is necessary to fix a security vulnerability
- Change human-readable strings, such as
detailin error messages
- Change the format of future identifiers and other opaque strings, such as adding, removing, or altering prefixes (like prf_ for a profile resource) and changing the length of the string
- Change an error’s HTTP status code or internal code to be more accurate or specific, such as changing a 400 to be a 404, etc.
- Adjust response behavior based on preferences supplied in the
Preferheader that were previously ignored.
What changes do we consider breaking?
- Remove a property in a response
- Restrict allowed properties in a request
- Rename properties in a request or a response. For example: changing
- Change a response to respond with an unexpected type. For example: returning
null, where the type specification does not include
String, where the type specification was
- Change a response to have a value outside of a documented range or format. For example: returning 7275551234 where an E164 phone format was specified or returning a negative number in a field specified to be greater than 0
- Remove a documented response header
- Require an additional request header