API Versioning And Compatibility [C IG]

Motivation

API versioning is a key aspect of maintaining compatibility throughout the lifecycle on an Enterprise MAM Solution. This policy describes how API versioning is implemented on the APIs of an Enterprise MAM Solution and what an API consumer can expect. It also describes what expectations an API has on its consumer with regards to maintaining compatibility.

The VidiCore API, as documented here, follows a different approach for compatibility and thus is not covered by this document.

The APIs of any 3rd-party components used in an Enterprise MAM Solution follow their respective guidelines for API versioning and/or API compatibility.

This policy complements the API Support and Deprecation Policy [C IG].

The information contained in this policy represents the current view of Arvato Systems' product on the date the document has been issued. This policy should not be interpreted as a legally binding commitment, but rather as subject to occasional change. This policy is for informational purposes only.

Breaking And Non-Breaking Changes – Stable APIs

Products, their components, and the APIs making their functionality accessible, do evolve over time. Thus, API changes are to be expected with each product release. All products of an Enterprise MAM Solution strive to implement all API changes in a way that existing applications may continue to work after updating a product or a component.

For the following sections it is helpful to distinguish between breaking changes and non-breaking changes:

An API change is considered non-breaking if neither the API consumer nor the API itself do not fail and show the same behavior (except bugs being fixed) with the new product version as shown with the previous product version.
If an API change does not fulfil this requirement, it is considered a breaking change.

To mitigate problems, resulting from breaking API changes when updating products, all APIs are strictly versioned.

An API version is considered stable when no breaking changes occur in this API version over its whole lifecycle. An API’s lifecycle usually covers multiple releases of a product.

API Versioning Scope

API versioning is done of the level of product components.

Consider a product consisting of components A, B, and C. All components start with API version v1 in version 20.1 of the product. Version 21.1 of this product requires a breaking change in component B’s API. This will increase the API version of component B to v2. The API versions of component A and C stay on v1.

When a new API version is introduced for a component, all API calls of this component are lifted to the new API version.

Responsibilities Of API Consumers

In order to avoid new API versions on very minor changes, all consumers of on Enterprise MAM Solution’s API need to adhere to these very simple rules:

An API consumer must not break if unknown or additional properties are returned in the response of an API call.
An API consumer should not make any assumptions on the URL structure before the version number. E.g. the URI change from https://host.company.com:31059/v1/Resource to https://host.company.com:32017/v1/Resource is not considered a breaking change. We recommend to make the full URI configurable.
An API consumer should not mix different versions of stable APIs.

API Version Numbers

API versioning is done via the URI of the API resource. The API version number is an integer value prefixed by the lower-case letter v. Example:

CODE

https://hostname.domain.com/v1/Resource

API version number always start with 1 on the initial release of an API. The API version number is independent of the product’s version number.

The API version number is incremented on breaking changes only. For non-breaking changes the API version number is not incremented. Thus, the API version number may stay the same over multiple product releases.

API Version Deprecation

As laid out in the API Support and Deprecation Policy [C IG] all API version except the latest stable one are considered as deprecated. API consumers should migrate to the latest API version within the timeframe defined by the API Support and Deprecation Policy [C IG].

Beta Versions

Products may come with versions of an API which still are under construction. These API versions are marked as BETA in the documentation. API versions marked as BETA are subject to breaking changes at any time and thus not stable.

Examples For Non-Breaking Changes

This list includes, but is not limited to, a series of examples of non-breaking changes:

Adding further properties to existing objects returned by API calls.
Changing order of properties in a JSON document.
Adding new resources to an existing API.
Adding query parameters to an existing API call as long as they are optional and the default value reflects the behaviour of the previous implementation.

Examples For Breaking Changes

This list includes, but is not limited to, a series of examples of breaking changes:

The URL-part of the API call after the version number changes.
Query parameters are renamed or removed.
Existing properties in the API call's body (e.g. JSON document) do change, e.g. from a single value to an array.
Existing properties in the API call's response (e.g. JSON document) do change, e.g. from a single value to an array.
The structure of the response body changes, e.g. the modified API call is returning an array instead of a single value.
Properties are removed from the API call’s response.