API Versioning

Common API is using Semantic Versioning 2.0.0 and Path Versioning for major versions.

Semantic

The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 and follows the semver specification. Version numbers are defined as major.minor.patch.
The major.minor portion SHALL designate the feature set. Typically, .patch versions address errors in this document, not the feature set. Details can be found here.

Example: If implementing Version 1.2.3, the major version is 1 and the minor version is 2. The last .3 indicates a patch release and does not change the way the API (should) behave. Minor versions are backward compatible as well.

Versioning concept

As versioning concept, Common API selected (just as The Berlin Group and Open Banking UK) path versioning. Therefore major versions are coded in the URI path: e.g. /common-api/mortgage/v1/applications.

Common API uses only the major version of the API in the path, so any changes that do not affect backward compatibility do not increase the major version number. A new major API version will be added if there are any changes that do affect backward compatibility as e.g.:

• Changing parameters (input, output)
• Removing fields
• Removing endpoints