Breaking and non-breaking changes
Periodically we’ll make changes to our API. This article defines what changes are considered breaking and non-breaking. We will only notify you in advance if a change is considered breaking.
Breaking changes
A breaking change can potentially cause a disruption to other applications using the API.
These are the types of changes that we consider breaking:
- Changing existing permission definitions
- Changing the functionality of an endpoint
- Removing an allowed parameter, request field, or response field
- Adding a required perimeter, request field, or response field
- Introducing a new validation
- Changing a non-required parameter to required
Non-breaking changes
A non-breaking change should not cause any disruption to applications using the API. We recommend designing your API implementation to accommodate these changes.
Non-breaking changes include:
- Adding new endpoints
- Adding new methods to existing endpoints
- Adding new fields – new fields in responses, new optional request fields or parameters, new required request fields with default values
- Adding a new value returned for an existing text field
- Changing the order of fields returned within a response
- Adding an optional request header
- Removing a redundant request header
- Changing the length of data returned within a field
- Changing the overall response size
- Changing error messages
- Fixes to HTTP response codes and error codes from incorrect code to correct code
Communicating changes
For any breaking API changes, we’ll notify the Account Holder by email and in an in-app message at least 14 days prior to the release.