Our API uses URL-based versioning. Each version is specified as part of the request path, for example:
• /api/v1/...
• /api/v2/...
• /api/v3/...

This approach makes versioning explicit, predictable, and easy to work with across different clients and tools.

Within a version of an endpoint we might offer multiple media types (accept or content-type header) that defines what kind of data will be send to the endpoint or is requested from the endpoint.

Please note, that not our complete API has a version, instead each individual endpoint has its version. We will introduce new versions of endpoints but not of the complete API.

Breaking Changes

The following things are considered breaking changes:

Modifying the payload structure
Removing parts in the payload structure
big changes in data processing

Adding items to a payload is not considered a breaking change.

Whenever breaking changes are implemented this will be done in a new version of the endpoint. Users can safely use previous versions and will not face any issues, as we will not introduce a breaking change into a version that is already released. When a new version of an endpoint is released the previous version automatically gets deprecated and will be removed at a later point in time.

📘
Legacy versioning
Earlier versions of our API used header-based versioning with media types (e.g., via the accept or content-type headers). This approach is now deprecated. All new endpoints and new versions of existing endpoints will be versioned with the URL-based approach. You can still use the old approach by using /api/... without the version in the URL but be aware, that this approach is deprecated and will be removed at some point from our API.
Stable
An implementation is considered stable once it solely has a version number in the Media Type:
application/vnd.xentral.VARIANT.v1+json
Early Access (Beta)
When API endpoints are still in development, or if we are working on a new version where the contract can still change, then we will label the version in the media type with beta:
application/vnd.xentral.VARIANT.v1-beta+json
Alpha
When defining a new API contract that is shared publicly for feedback, the API is considered in the alpha stage.
Kindly note that this endpoint has been released, but the data you get is dummy data, meaning you can start working on building your integration, but we are still working on these endpoints.
application/vnd.xentral.VARIANT.v1-alpha+json