A major version update indicates breaking changes in an API. The major version of an API is part of the URL path of XXX for calling a service API.
A change is considered as breaking, if the behavior of an existing documented API feature is changed in a way such that clients using that feature might not work anymore. To be able to work with the updated version, the clients need to be modified. Breaking changes are, e.g.:
Removing, renaming, or moving API entities such as:
endpoints
HTTP methods associated with endpoints
operation query, body, or header parameters
schema properties
authorization roles
Changing the way how existing features need to be used, e.g., by introducing new preconditions to be fulfilled
Changing an already present workflow
Making optional parameters or schema properties mandatory
Changing documented functional or non-functional behavior in significant ways
A major version update resets the minor and patch version values to zero initially. For example, in case an API with version v3.1.2 undergoes a major update, the version value is changed to v4.0.0.
Minor Version
A minor update indicates backwards compatible changes in an API. Clients that are compatible with XXX minor update rules will continue to work with the updated API version.
A change is considered as backwards compatible, if optional new features are added to an API. For example, adding optional API entities such as the ones mentioned above for breaking changes. A client is considered compatible with XXX minor update rules if it tolerates new API entities, e.g., new optional schema properties or new error responses.
A minor version update resets the patch version values to zero. For example, in case an API with version v3.1.2 undergoes a minor update, the version value is changed to v3.2.0.
Patch Version
A patch version udpate only relates to the API specification document. The implementation remains unchanged. Patch updates are corrections or improvements of descriptions or examples in the API specification. Patch updates might also fix a mismatch between specification and actual implementation of an API. The latter case is particularly important for client developers, who want to develop compatible clients.