46865882c6
PSA abstraction layer with provider pattern, ConnectWise integration (connection management, ticket linking, note posting, status updates, member mapping), Integrations page UI, Fernet credential encryption, in-memory TTL cache, 6 DB migrations, ConnectWise API reference docs.
3.7 KiB
-
Last updated
Mar 31, 2023
Starting with 2019.1 the API is now tied to the ConnectWise PSA release cycle. Previously the API was versioned as it's own entity and followed a format such as 3.0.1. To provide clarity around the API Versioning and to make it easier for consumers, we have replaced 3.0.0 with the specific ConnectWise PSA version that the API model was released on.
If you develope your API against 2019.1 and pass in the version 2019.1, you will continue to get the models for 2019.1 even if we change them in 2019.2. What this means is that each time we release a breaking change, you have a period of time to switch over to the new version. We do not release new models every release, however you can still target a version that did not have any changes. For instance, lets say in 2019.1 we have a specific ticket model called A. In 2019.4 we update tickets to have model B. If you pass 2019.1, 2019.2 or 2019.3, you will get model A, which is 2019.1.
By default all requests will receive the latest version of our API endpoint. As breaking changes are released, each individual API endpoint, may receive an updated version. In order to prevent your integration from breaking, we encourage you to request a specific version using an Accept header. For all production level integrations we recommend using this Accept header concept and for all development and testing work, we recommend using the latest version of the API. We will regularly deprecate old models of the API.
What is a breaking change?
Breaking changes are defined as any change to the APIs that could result in an error being returned by the SDK. The SDK is a JSON interpreter and as long as you develop your code the way a modern JSON interpreter would, you shouldn't have any issues. If you hard code every field, you will have issues that we don't consider breaking.
Examples of breaking changes:
-
Renaming a field (fixing a typo)
-
Changing a field's data type (such as from an int to a decimal, or from editable to read only)
-
Changing the response type (such as from an object to an array of objects)
-
Validation changes (fields now required that previously were not)
NOT a breaking change:
-
Adding new fields
-
Adding new endpoints
-
Making a read only field editable
-
Making a field no longer required if it was previously required
As we release breaking changes the individual endpoint will be versioned when applicable. The previous version will be immediately be considered deprecated but supported for 12 months. Please note that some endpoints cannot be versioned.
Formatting Version Header
We try to make it as simple as possible to format your version header. We use an accept header that lists our JSON schema as well as the version following. Accept headers tell the server what type of information you are expecting to get back. This makes it a perfect fit to add our version to as this tells the server that you want xyz version back.
1 |
Accept: application/vnd.connectwise.com+json; version=``2019.1 |
|---|
Per Endpoint
If you are not ready to update to the latest API Models for your entire integration, you can change your accept header to be on an endpoint by endpoint basis. We recommend that you keep a singular version across your integration, but will support it either way. Anytime you test your integration and validate it against a version, update your version header even if we are not deprecating the version you are on. We may do so without warning, or give you very little time to make changes.