Versioning and Compatibility¶

The COMOS Web REST API will evolve over time. Additional features will be added and existing features might be extended, adjusted or even removed. Likewise, the API clients will evolve. A client using the COMOS Web REST API might not be deployed or updated at the same time as the API. Instead, a client might be updated before the COMOS Web REST API is updated and vice versa. Different versions of a client might be used at the same time.

An older client might not know about new COMOS Web REST API features but should be able to use older features or even to detect that a feature might not be available anymore. A newer client should be able to decide which features are already supported by the COMOS Web REST API.

The API uses a versioning strategy to enable the following:

• Both the COMOS Web REST API and the clients using the API shall be able to evolve independently to a certain extent.
• Clients shall be able to detect existing API features during run-time and, optionally, to provide feedback on this.
  (For example, by deactivating control elements in a user interface)

Semantic Versioning¶

Semantic Versioning is used to version features of the COMOS Web REST API. A version number is indicated in the following format: MAJOR.MINOR.PATCH Each part is a non-negative integer consisting of digits only and without leading + or leading zeros.

Versioning and client behavior¶

A client SHOULD implement the following behavior.

If a client has been built against a specific feature version, e.g. version 2.3.5, the following compatibility is assured:

The MAJOR version on the server is greater¶

• The client MUST NOT use the server version. It MAY notify the user about this fact, e.g., by displaying a message or by deactivating or removing specific user controls.

The MAJOR version on the server is equal¶

• The MINOR version on the server is greater.
  The client can use the feature and all the endpoints known to the client. The functionality of the feature has been extended since the client was implemented, but only in a compatible way.

• The MINOR version on the server is equal.
  The client can use the feature and all the endpoints known to the client. The functionality of the feature has not changed.

• The MINOR version on the server is smaller.
  The client can use the feature, but only the subset that has already been available up to the server version.

The MAJOR version on the server is smaller¶

• The client can use the feature, but only the subset that has already been available up to the server version (including the MINOR version).

A change of the PATCH version does not affect the compatibility.

If a new MAJOR version of a feature is available, a new client implementation SHOULD adjust to the new version.

For compatibility reasons, a feature MAY be available in multiple versions temporarily, usually in the current MAJOR version and the previous MAJOR version, e.g., 1.7.3 and 2.0.1. If a feature is available in multiple versions and a client discovering the features can handle multiple versions—especially MAJOR versions—, the client SHOULD use the newer version as this is generally an improvement of the previous versions.

Clients MUST ignore versions with invalid version numbers

A client MUST be able to handle unknown additional properties — e.g., in a JSON response — without breaking if the MINOR version of the feature has increased since implementation of the client.