Versioning

The version of the AzoraOne API will control the API and webhook behaviors, such as parameters accepted in requests and response properties.

Backwards-incompatible changes

We strive to consistently improve the API and our service to you. Some changes to the API might (in rare cases) impact or even break your existing application:

  • Adding authentication or authorization rules

  • Removing or renaming resources

  • Removing request parameters

  • Adding new required request parameters

  • Removing response parameters in existing API responses

  • Changing permissions for existing resources

We consider changes like these backwards-incompatible changes. The AzoraOne APIs use versioning to roll out backwards-incompatible changes over time. To avoid breaking your code, a new version of the API will be released when backwards-incompatible changes are made to the API. This allows you to upgrade when you are ready.

Backwards-compatible changes

Regardless of version, we anticipate your code to be able to handle the following changes:

  • Adding new API resources

  • Adding new attributes to existing API responses

  • Changing the order of attributes in existing API responses

  • Adding new HTTP methods for a resource

  • Adding new optional request parameters

  • Adding new event types. Your webhook listener should handle unfamiliar events types.

We consider these changes backwards-compatible. Backwards-compatible changes will be released without introducing new versions.

Making versioned requests

The API version is required to be included within the URL in all API calls. In order to make a versioned request you add the version number to the URL path:

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

The API call will fail if the version is not included or if the requested version is unsupported.

What is the latest API version?

The latest AzoraOne API version is v1. The documentation displayed on the Docs page describes the latest API version. Documentation for older versions (currently none) will be provided in links.

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

Where do I find information on backwards-incompatible changes?

Backwards-incompatible changes will be documented in the changelog as part of every version release.

Why versioning?

The goal with our API versioning is for you to be able to do the necessary adjustments at you own pace when a change in an API might affect your application. Proper API versioning is important in web development but even more so in mobile development. This is due to a person using your app on their phone may take a long time to upgrade (or may never upgrade).

AzoraOne is a product developed by Arkimera Robotics.