How versioning applies

Chorus NZ is committed to improving and enhancing our APIs and we will make changes from time to time.

We will let you know, a minimum of 30 days, in advance that the changes are coming, and provide you with release notes and RAML outlining the changes so you can assess what, if any, changes are required to your application.

Minor version changes

Chorus considers that customers will not need to make changes as the release is non-breaking. The same URL will be used. This assumes that customers have implemented the API in accordance with this section on versioning

Minor version changes will not change the URL of the API. Complete version details will can be seen in either the X-Chorus-API-Version header or by calling the /version resource on the API.

The following changes are considered minor and your code should be developed so that it will not break with these changes:

  • Addition of new resources (with potentially new schema).

  • Addition of new non-mandatory request parameters or attributes.

  • Addition of new data fields returned in responses.

  • Change in the order of data fields returned in responses.

Patch release

A patch release will not deliver new functionality for an API; this will be for defect fixing only.

Major version changes

Chorus considers that customers will need to make changes to consume this API – to mitigate the impact of this a new URL will be released and the existing URL will continue for a reasonable period so you can implement the new API when it is convenient, i.e. there will be no immediate impact as the status quo will continue.

Major versions of existing APIs will be created to include significant enhancements or new features relating to our services. Before you upgrade to a new API version in your own production environment we recommend you carry out regression tests against the new API version.

Changes that require a version change are:

  • Renaming of resources, parameters, attributes.

  • Inclusion or removal of resources, mandatory parameters and mandatory traits.

  • Restructuring the API interface.

We will issue:

  • New version introduced with a new version number (the version number is incremented).

  • New API Portal, including new set of schema (RAML, YAML, JSON Schema).

  • Sample JSON and other documentation.

Decommissioning an old version of an API

Older versions of the APIs will be deprecated; this means the API will remain available for use by existing consumers but will not be available to new consumers.

If we decide to decommission a deprecated API, the following communications will apply:

  • 90 days consultation, and then:

  • 3 months' notice – if minor

  • 12 months' notice - if major; or

  • 20 business days' notice – if RSPs agree trivial,

And if there are no users left on the API, this may be 20 days' notice.