API Lifecycle¶
All endpoints in this API are versioned using a version number that appears in the URL.
For example, v3 endpoints look like this:
Older version APIs may still be used unless they are deprecated, in that case see Deprecation.
Breaking changes¶
Any breaking changes to the API will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:
- removing an entire operation
- removing or renaming a parameter
- removing or renaming a response field
- adding a new required parameter
- making a previously optional parameter required
- changing the type of parameter or response field
- removing enum values
- adding a new validation rule to an existing parameter
- changing authentication or authorization requirements
- adding enum values
Any additive (non-breaking) changes will be available in the existing API version. Additive changes are changes that should not break an integration. Additive changes include:
- adding an operation
- adding an optional parameter
- adding an optional request header
- adding a response field
- adding a response header
Deprecation¶
In some cases, we may have to remove an endpoint or older versions of an endpoint. We might do this, for example, if the platform no longer supports the underlying functionality exposed by the endpoint.
If we have to replace or remove an endpoint, we will announce the change at least twelve months in advance, and provide continued support and SLA guarantees in the meantime.