Versioning and API Changes

Versioning

Each release or iteration is assigned a unique version number, generally formatted as “major.minor.patch”:

Major Version Changes: Significant updates that introduce breaking changes are designated by incrementing the major version. This resets both minor and patch versions to zero. For example, an upgrade from v3.1.2 to v4.0.0 indicates a major change. Major versions result in a change of the URL path for the APIs, which are subject to the major change.

Minor Version Changes: Smaller, backward-compatible feature additions or changes that reset the patch version to zero. For example, an update from v1.11.29 to v1.12.0 reflects a minor version change.

Patch Versions: Address bug fixes and minor adjustments that do not alter the API’s functionality, focusing solely on improvements to the API documentation and fixing mismatches between the documentation and the actual implementation.

Types of Changes

Major Changes (Breaking Changes): Involve changes that can cause existing applications to fail unless they are updated to align with the new API specifications, such as:

removing or renaming of API entities such as endpoints or HTTP methods

adding or removing mandatory parameters (query, body, header)

changing authorization roles.

altering response structures

changing preconditions for feature usage

significant modifications to documented behavior.

Minor Changes (Backward Compatible Changes): Typically involve adding new features that do not disrupt existing functionality. This includes:

Adding new API resources

Introducing new optional request parameters or response properties

Adding new enum values or optional request headers

Minor adjustments to API descriptions or property order

Deprecation Policy, Compatibility, and Migration

A major API version can be deprecated following a designated “coexistence time” after the release and communication of a newer version. During this period, partners can still use the old version while preparing to transition to the newer release.

Partners are notified via email and given a six-month period to integrate the new major version. This ensures sufficient time for necessary adjustments to their integrations.

Extension requests beyond the six-month period are evaluated on a case-by-case basis.

Versioning#

Types of Changes#

Deprecation Policy, Compatibility, and Migration#

Versioning

Types of Changes

Deprecation Policy, Compatibility, and Migration