Our versioning
Overview
Chorus is dedicated to improving our suite of APIs. Therefore, we will periodically make updates to enhance your experience by offering improved products and services, stability, and reliability. Our intent is to minimise the impact of change whenever possible, and if unavoidable, we will ensure breaking and mandatory changes are designed well with you to reduce unnecessary negative impacts. Our API versioning policy will ensure that changes are categorised and managed consistently.
Semantic versioning
Chorus uses semantic versioning in the MAJOR.MINOR.PATCH format. Each number is incremented sequentially to denote the following changes:
- MAJOR: the API release contains changes that are not backwards compatible in the current version
- MINOR: the API release contains additional capabilities and non-breaking (backwards-compatible) changes
- PATCH: the API release contains non-breaking bug/fix changes only.
Version numbers are visible within the Mulesoft Anypoint Platform, and users can select the Major: Minor versions. Patch versions can’t be selected.
Change classifications
The following change classifications apply.
Change classification | Change classification reasons | Chorus will provide |
New API or New Version |
| Minimum 30 days notice* (not working days) including:
*If a new version is released, the previous version will be deprecated, giving at least 12 month’s notice to users. See the Decommissioning and support section on this page. |
Mandatory change | Any API change that requires customers to adopt by a certain date (for example, regulatory changes)
| Negotiable notice period (see Mandatory Change section), including:
|
Minor version change |
| Minimum 30 days notice (not working days) including:
|
Patch | Defect fixes only, no impact
| Patch version number change (Changelog only)
|
Note: If a notice period falls across December and January, two months will be added to the overall notice period.
Minor Changes
Chorus considers that customers will not have to make changes for minor versions, as they will be non-breaking (backwards compatible). The same URL will be used. However, this only applies if customers implement their code to handle these changes without breaking. Customers can check the full version details by calling the /version resource in the API or by looking at the Changelog documentation.
Note: some of the older Chorus APIs return full version number in the X-Chorus-API-Version header - this approach has been deprecated.
Major or breaking changes
New versions of existing APIs will be created to include significant enhancements or new features relating to our services. Chorus considers that customers must make changes to consume this API therefore we will release a new URL (new API full version) to mitigate this impact. The most recent previous full version will continue to be supported for 12 months (see Decommissioning and Support). Before upgrading to a new API version in your production environment, we recommend conducting regression tests against the latest API version. Where we require the new API to be consumed within 12 months, this will be considered a Mandatory change, see below.
Note: New APIs may be released into beta quickly before being considered ‘stable’. The purpose of the API during this time is for improvement opportunities, including the ability to make improvements/updates quickly. During any beta phase the notification timelines for changes within this policy will not apply.
Mandatory changes
Mandatory change is defined as when Chorus is required to change, and/or we require you to adopt any API change on a specific date (excluding previous versioning decommissioning*). Therefore, these changes may require a longer notice period and should be considered rare.
When Chorus believes a Mandatory change to an API is required, we will:
- invite all affected users to design the change with us collaboratively
- where we will share the necessary change and our proposed solution
- understand from you what the impact of the change may be for your organisation
- provide opportunity for your input to the proposed design, and
- provide opportunity for your input into a reasonable notice period (subject to the type of change), before finalising the change classification and date for change.
Decommissioning and support*
The previous version will be deprecated upon publishing a new major version that is stable (not in beta). This means the API will remain available for use by existing consumers and will be supported but unavailable to new customers.
A 12-month decommissioning notice will be issued upon deprecation.
However, if no users remain on the API, we may issue a 20 business days decommissioning notice.