Integration Principles
API Versions
The API version will influence the request and response object structures as well as the functionality that is available through the API. A new version of the API will be introduced only if we roll out a backwards-incompatible change that may impact your existing integrations. You can manage when to upgrade to the latest version, helping ensure your integration is not disrupted as new functionality becomes available.
Major Version
The major version (i.e., /v1/ ) represents a major technology shift between versions of the API. Changes in the major version are reserved for large-scale changes to the API that fundamentally change integration requirements from the previous version. Modified business domain models, re-design of functional flows, or change in API resource patterns are all considered major changes. Changes to a major version are rare and typically require an extended deprecation cycle (~2 years) from prior versions to allow all consumers of the API to adapt.
Backwards Compatibility
Your integration should take the following backwards-compatible changes into consideration so as not to break when additional fields are added to the API.
What Is Considered a Backwards-compatible Change?
- Adding API resources or adding new properties to existing API resources
- Modifying the order of parameters or JSON object elements
- Adding optional request parameters to API methods
- Adding a webhook event type
What Is Considered a Backwards-incompatible Change?
- Removing an API resource
- Removing an API resource's object attribute
- Changing required parameters or JSON object elements
- Removing previously supported API calls