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
detail in 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
Prefer header 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
null or returning
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