API essentials

Our versioning

Note: Last updated 2017. This policy is currently under review and an updated policy is expected in late 2023.

Chorus 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 when changes are coming, and provide you with release notes and RAML outlining these changes. You can assess what, if any, changes are required to your application.

Minor version changes

For minor versions, Chorus considers that customers will not need to make changes as the release will be 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 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 it will not break with these changes. We may:

  • add new resources (with potentially new schema)
  • add new non-mandatory request parameters or attributes
  • add new data fields that are returned in responses
  • change 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

For major version changes, Chorus considers that customers will need to make changes to consume this API. To mitigate the impact of this, we will release a new URL and the existing URL will continue for a reasonable period so the new API can be implemented when 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 could include:

  • renaming resources, parameters or attributes
  • adding or removing resources, mandatory parameters or mandatory traits
  • restructuring the API interface.

We will then:

  • introduce the new version with a new version number (the version number is incremented)
  • issue a new API Portal, including a new set of schema (RAML, YAML, JSON schema).
  • issue a 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, we will provide 90 days' consultation and then issue:

  • 3 months’ notice – if a minor change,
  • 12 months’ notice – if a major change, or
  • 20 business days’ notice – if RSPs agree it is a trivial change.

And if there are no users left on the API, we may instead issue 20 business days’ notice.