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	Breaking change that is not backwards compatible with the existing version (also called major change) Renaming resources, parameters or attributes Removing resources, mandatory parameters or mandatory traits in responses New input fields or resources which are required or impact the process outcome when undelivered Restructuring the API interface Changing error codes for specific situations, except for the refinement of generic errors	Minimum 30 days notice* (not working days) including: a new full API version, URL, and version number a new set of schema and full technical documentation supporting contextual information for business, process, and operational changes _{*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: Advance roadmap updates If agreed as a Major change – all Major change artefacts (above) If agreed as a Minor change – all Minor change artefacts (below)
Minor version change	New resources (with potentially new schema) New non-mandatory request parameters or attributes Changing existing mandatory parameters to optional New input fields or resources which are optional and do not impact the process outcome (i.e. default behaviour remains the same) New data fields that are returned in responses Introducing new error codes for specific situations as result of the refinement of generic errors	Minimum 30 days notice (not working days) including: Change log release notes Minor version number change Updated technical documentation Supporting contextual information for business and operational changes
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.

API Developers