Versioning and API lifecycle #40076

vmuzikar · 2025-05-29T15:36:39Z

vmuzikar
May 29, 2025
Collaborator

This discussion is a design proposal for versioning in the new Admin API v2.

Versioning will be independent for each "API resource group".
- E.g. there can be Clients API v2, Users API v3, Realm API v4, etc.
- An "API resource group" can be a single endpoint and a single representation, or multiple endpoints and resources where it makese a sense.
- The API won't be versioned as a whole, in practice there won't be an "Admin API v2".
- Realm API is a special case as it potentially includes all other subresources (Clients, Users, etc.) which each has an individual API version.
  - The standard Realm representation won't include any of the subresources. Only a dedicated import/export endpoint will.
Versioning will be implemented using path parameter.
- E.g. /admin/v2/clients, /admin/v3/users.

Versions lifecycle

Any breaking changes will be done only through introducing a new API version.

What is a breaking change: fields renaming or removal from the representation, default values changes, endpoints removal or renaming or changing their existing behaviour, etc.
What is not a breaking change: fields addition, adding a default for previously required field, adding a new endpoint or new HTTP verbs, new parameters, etc.

The intention is to keep the changes as the non-breaking as much as possible to avoid introducing new API versions too often. To support this approach, default values should be essentially kept at minimum. Before introducing one, ask a question whether the default really brings any semantic value to the user, and is not likely to change in the near future.

The concept is to have at most 2 API versions (for a given "API resource group") at a time: stable, stable/preview, deprecated/stable.

Non-breaking changes will be done in any Keycloak minor release to the stable API version and clearly marked as "Available since Keycloak X.Y".
Breaking changes can be done only to a preview version of an API.
- If no preview version exists, add in a minor release.

Replacing a stable API version

Promote the preview API version to stable in the next minor release but keep the old stable as the default.
In the next major release, deprecate the old stable version, and make the new stable default.
In the next subsequent major release, remove the old stable version.

The major drawback of this approach that it can take up to 6 years (two major versions) to deprecate and finally remove an old API version.

Navigation Menu

Repository navigation

Versioning and API lifecycle #40076

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Versioning and API lifecycle #40076

Uh oh!

Uh oh!

vmuzikar May 29, 2025 Collaborator

Versions lifecycle

Replacing a stable API version

Replies: 0 comments

vmuzikar
May 29, 2025
Collaborator