Versioning

Versioning strategy

SCALAR teams make the commitment always to try avoiding introducing breaking changes so that the existing integrations made by developers don't get broken. A breaking change is specified as a change to the contract that forces to create a new version (v1 to v2).

The effect for the developer is that he will need to change his integration in a reasonable timeframe. Following the deprecation strategy of old versions in normal cases the backwards compatibility of an old version will be one year and will be clearly specified. It is the responsibility of the developer to change within the year to the new version.

All changes will be clearly mentioned in the Change Logs section explaining the differences and impact.

What is a breaking change?

A breaking change is a change that forces to create a new version because the existing contract cannot be manipulated to be backwards compatible.

Some examples of a breaking change:

Changes to existing permission definitions.
Removal of an allowed parameter, request field or response field.
Addition of a required parameter or request field without default values.
Changes to the intended functionality of an endpoint. For example, if a DELETE request previously used to archive the resource but now hard deletes the resource.
Introduction of a new validation.

Some examples of non-breaking changes that don't require the developer to change the integration:

Addition of new endpoints
Addition of new methods to existing endpoints
Addition of new fields in the following scenarios - new fields in responses
Addition of new fields in the following scenarios - new optional request fields or parameters
Addition of new fields in the following scenarios - new required request fields that have default values
Addition of a new value returned for an existing text field
Changes to the order of fields returned within a response
Addition of an optional request header
Removal of redundant request header
Changes to the length of data returned within a field
Changes to the overall response size
Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.
Fixes to HTTP response codes and error codes from incorrect code to correct code

Versioning strategy explained

SCALAR APIs follow the SemVer (https://semver.org/) specification – the API's major version is updated whenever a breaking change is introduced. Internally (non-visible for the developer), minor and patch versions are updated whenever a new functionality is added or for backward-compatible updates.

When a new major version of the Datahub API is released, developers can choose to either continue using an existing major version or migrate to the new one but after the deprecation period the developer must make sure that the developer has moved to the new version.

The internal version of the API uses the 1.2 format, so it looks as follows:

MAJOR.MINOR

Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct host.

Minor versions: These are transparent to the client and used internally for backward-compatible updates. We usually communicate in Change Logs to inform clients about a new functionality or a bug fix.

For implementing versioning the URL Path approach is used

Deprecation of any API will be in accordance to Deprecation Policy.