Breaking Change and Deprecation Policy - kmd-identity/documentation GitHub Wiki

API endpoints in KMD Identity follow a deprecation cycle of 12 months. This means 12 months notice are given before retirement.

Endpoints are versioned initially at 1.0 and this increments by 0.1 for every new version.

When are new versions made?

A distinction between backwards-compatible and breaking-change is made, to determine when a new version is required.

The following are examples of non-backward compatible changes:

• Changes to the URL or fundamental request/response associated with a resource
• Removal, rename, or change to the type of a declared property
• Removal or rename of APIs or API parameters
• Addition of a required request header

The following are examples of backward compatible changes:

• Addition of properties that are nullable or have a default value
• Addition of a member to an enumeration
• Removal, rename, or change to the type of an annotation
• Introduction of paging to existing collections
• Changes to error codes
• Changes to the order of properties
• Changes to the length or format of opaque strings, such as resource IDs

Beta-endpoints

When an endpoint is subject to future change or removal, thus not meant to be relied upon in a production-environment, it will be available under the path-prefix '/beta/'.

Deprecated versions

As of writing, no versions are deprecated.