Versioning

API versioning is a vital practice that allows us to roll out new features and improvements without breaking the existing functionalities of our application programming interface (API). This article explains the versioning approach used by our API and how it impacts your interaction with our platform.

Why is versioning necessary?

Versioning is necessary to manage changes and updates to our API over time. As we continually strive to improve our platform by adding new features or modifying existing ones, we use versioning to avoid conflict with the existing functionalities used by our clients and to provide them with the flexibility to adopt changes at their own pace.

How we implement versioning

In our system, we use semantic versioning. API versions are denoted as v1, v2, v3, and so on. Each version reflects a stable release of the API with a specific set of functionalities.

• Major versions: They indicate a major release of our API which includes non-backward compatible changes.
• Minor versions: They indicate a minor release that includes backward-compatible feature additions.
• Patch versions: They represent a patch release that includes backward-compatible bug fixes.

Using versions in API requests

While making an API request, the version of the API intended to be used should be specified in the URL or in the header. For instance, if you are using version 1 of our API, your API request URL should include /v1/. However, if not specified, the API will default to the earliest version.

Example: 
GET https://api.example.com/v1/users

Migrating to a new version

When a new major version of our API is released, developers have a grace period to switch their application to use the new version. We communicate this period in our release notes and API documentation.

In conclusion, understanding versioning is vital for API consumers to manage their integration with our platform and to benefit from the continuous improvements we make to our API.