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.