Versioning
What is versioning?
Versioning means that different versions of AzoraOne can be released with different behaviours, resources, requests, responses and more.
The goal of versioning is to prevent backwards-incompatible changes from breaking your current integrations. These changes are released as a separate version, so you 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 to AzoraOne.
When a new version is released, you'll have approximately one year to upgrade before the old version is deprecated.
We've worked hard since the launch of AzoraOne to avoid backwards-incompatible changes and to plan carefully for future needs. As a result, we've never needed to release a second version: our first version number is still our latest one.
This doesn't mean AzoraOne stands still. Backwards-compatible improvements are released continuously under v1. You can follow all of these in the changelog.
Making versioned requests
To make a versioned request, add the version to the base URL.
https://api.azora.one/{api}/{version}The version in the base URL is required and needs to be a valid version number. Currently, the only valid value is v1.
Versioning applies to the API as a whole, not to individual resources or operations. All endpoints under a given {api} value share the same version.
Different types of changes
There are two types of changes that can be made to AzoraOne.
- Backwards-compatible changes
The changes will not break existing integrations and are therefore released under the latest version. - Backwards-incompatible changes
The changes can break existing integrations and are therefore released as a new version.
Backwards-compatible changes
Backwards-compatible changes are released without introducing a new version 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 your current integration.
Backwards-incompatible changes
Backwards-incompatible changes are 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 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.