Change Policy¶
This policy applies to all incoming and outgoing APIs for Copper CRM that are accessible to partners, including:
- Developer API
- Copper SDK
- Webhook payloads
From time to time Copper will change our APIs as we improve our products and services.
We divide changes into two types — backwards compatible and incompatible changes — and handle them separately.
Backwards-Compatible Changes¶
Most changes have a low probability of impacting partners, and we regard these changes as backwards-compatible:
- Adding a new API version
- Adding new API endpoints, SDK methods, or Webhook payload types
- Adding new fields to responses, return values or Webhook payloads
- Adding new optional parameters or fields to requests or methods
- In these cases we will provide sensible defaults that match the previous semantics
- Adding new kinds of response objects in cases where an endpoint can return multiple kinds of objects (e.g. activity log events)
- Adding or editing documentation on endpoints
- Adding or editing error or status messages returned from endpoints
- Resolving bugs or other cases where an endpoint’s actual behaviour does not match the intended or documented behaviour
- All changes to undocumented endpoints
What You Can Expect From Copper¶
We will occasionally make these changes to our APIs. When integrating with Copper’s APIs and SDKs, your code should be robust to these sorts of changes and should handle them without modification.
Change Process¶
When Copper makes backwards compatible changes to our APIs, we will modify the documentation to reflect the changes. For significant changes, we will announce changes according to our Communication Plan (see below).
Incompatible Changes¶
Any changes that are not listed above are considered backwards incompatible (“breaking”) changes, including:
- Removing an entire API version
- Removing or renaming API endpoints
- Adding new required request parameters or fields, or making an optional parameter required
- Removing parameters from a request
- Removing fields from a response or Webhook payload
- Changing the meaning or semantics of an API endpoint or Webhook event type
- Changing the meaning or semantics of fields within a response body or Webhook payload
- Changing default values for request parameters or fields
- Changing our access control mechanisms in a way that requires changes to continue to use the APIs for legitimate purposes that were previously allowed
What You Can Expect From Copper¶
Because these changes have a high chance of impacting partners, Copper will not make these changes without advance notice, as described below. You can assume that these changes will not be made unexpectedly.
Change Process¶
When Copper decides to make an incompatible change, we will mark the obsolete version as deprecated in our documentation and announce the deprecation to partners as described in the Communication Plan below.
We will continue to support deprecated APIs for at least six months from the announcement to allow partners to transition their integrations.
Communication Plan¶
When Copper makes significant changes to our API, we will notify our partners through the following channels:
- API documentation and changelog
- Support articles describing the changes.
- Email to the owners of all active API keys describing the changes.
In the case of breaking changes, that announcement will include a migration plan with advice for how to adjust your systems to avoid using the deprecated feature, and a timeline for when the deprecated feature will be removed.
Glossary¶
| Term | Definition |
|---|---|
| Field | A key-value pair in a JSON document, such as in a request or response body. Example: In {id: 1, name: "Clever User"}, the id and name and their attached values are “fields”. |
| Parameter | A value that’s passed to the server in a URL, or in an SDK method. Examples:
|