Versioning

What is versioning?

Versioning means that different versions of AzoraOne can be released with different behaviors, resources, requests, responses etc.

The goal of versioning is to prohibit backwards-incompatible changes from breaking your current integrations. These changes will be released as a separate version so that developers have time to make the required changes before switching to the new version.

We recommend staying up-to-date with the latest API version to take advantage of the latest improvements made to the AzoraOne API.

When a new version is released users will have approximately one year to upgrade to the newer version before the old version is deprecated.

Since the launch of AzoraOne in 2017 we have only had one version.

Making versioned requests

In order to make a versioned request you need add the version to the base URL.

https://api.azora.one/{api}/v1

The version in the base URL is required and needs to be a valid version number.

The one and only version of AzoraOne is currently "v1".

Different types of changes

There are two different types of changes that can be made to AzoraOne.

  • Backwards-compatible changes
    The changes will not break existing integrations and will therefore be released under the latest version.

  • Backwards-incompatible changes
    The changes can break existing integrations and will therefore be released as a new version.

Backwards-compatible changes

Backwards-compatible changes will be released without introducing new versions of the API.

  • Adding new resources

  • Adding new operations

  • Adding new attributes to responses

  • Adding new optional attributes or query parameters to requests

  • Changing the order of attributes within existing requests or responses

Your code should be able to handle these changes without breaking the current integration.

Backwards-incompatible changes

Backwards-incompatible changes will be released in a new version of the API.

  • Removing or renaming existing resources

  • Removing or renaming existing operations

  • Adding new required attributes to requests

  • Removing or renaming existing attributes within requests or responses

  • Removing or renaming existing attributes or query parameters within requests or responses

  • Adding or modifying authentication rules

Your code does not have to handle these changes upon release as they could break your current integration. You can make the necessary changes in your code before transitioning to the newer version.

Information on changes

You can find information on all backwards-compatible and backwards-incompatible changes in the changelog.