API Default Values Principles #38551

slaskawi · 2025-03-31T11:26:43Z

slaskawi
Mar 31, 2025

Summary

This discussion thread provides options and discusses the advantages and trade-offs of providing default values for the v2 Admin APIs.

The following design assumptions have been taken into consideration for this proposal:

HTTP GET should return exactly what was POSTed.
- Otherwise, all controller-like software will detect state drift and trigger reconciliation.
Unless necessary (and documented as a breaking change), the resource shouldn't change its behavior during an upgrade.
- Otherwise, customers will notice different and inconsistent behavior between versions, which is problematic for larger fleets of servers behind a reverse proxy or load balancer.
There needs to be a way to obtain a full client representation with all default values inlined.
- This is primarily for GitOps, reporting, and debugging purposes.

Proposed API Behavior

This proposal introduces two modes for each resource for HTTP GET: "Requested," which returns exactly what was sent by the POST, and "Runtime," which represents the resource used by the Keycloak runtime. A new query parameter (runtime=true) will be introduced to the APIs to obtain the latter.

Let's consider a very simplistic Client API example. For the sake of this example, let's assume it consists of only two fields: client_id, which must be supplied by the client, and protocol, which defaults to "openid-connect" if not supplied. Here's how the API would behave:

HTTP POST:

POST /admin_v2/realms/master/clients
{
  "client_id": "my-client",
}
Returns HTTP 201 with requested Client Representation
{
  "client_id": "my-client",
}

HTTP GET:

GET admin_v2/realms/master/clients/my-client (note client_id not Keycloak internal UUID)
{
  "client_id": "my-client",
}

It is also possible to add query param “runtime=true” and get the full Representation:
GET admin_v2/realms/master/clients/my-client?runtime=true
{
  "client_id": "my-client",
  "protocol": "openid-connect", ← this one is taken from the defaults
}

HTTP PUT:

PUT admin_v2/realms/master/clients/my-client
{
  "client_id": "my-client",
  "protocol": "saml", (just for the sake of illustration - we need to think about transitions more)
}

Ephemeral Default Values

Default values might either be persisted in the resource model or remain ephemeral.

The obvious advantage of persisting default values is its simplicity in handling migrations. Once a client is created via the API, corresponding default values are pulled and persisted in the model, making it ready to use. The main trade-off is that if a default value gets updated later, none of the existing clients will receive the new value.

On the other hand, ephemeral default values are pulled every time the client is manipulated by the API or used by Keycloak runtime. The main advantage here is design simplicity, but the trade-off lies in maintaining backward compatibility.

After a discussion tracked here, we decided to pursue ephemeral default values.

Alternatives Considered

When working on this proposal, the working group considered several different approaches. Some of them are outlined below:

A Kubernetes-like API approach with separation into spec and status.
Persisted values and their impact on design.
Combining the "Requested" and "Runtime" API models.

References

Related discussions:
- Declarative configuration API #33049
- What is not working well with the current Admin APIs? #37655
The Keycloak Admin API v2 WG Meeting Notes:
https://docs.google.com/document/d/1UUGeudHOalWTHX31vvTi8-PPpzOXxRQb0pSUR8eetEA/edit?tab=t.0#heading=h.2r8egkh457sa

vmuzikar · 2025-05-16T11:19:47Z

vmuzikar
May 16, 2025
Collaborator

A follow-up discussion around defaults is at #39547.

0 replies

vmuzikar · 2025-05-29T15:32:12Z

vmuzikar
May 29, 2025
Collaborator

Updated Defaults proposal

Defaults will be in the end persisted. The reasoning is:

We want to provide a stable spec contract. I.e. a given API version (which also includes the spec/representation) also covers the default values which do not change with Keycloak versions. Defaults can change only when the API version changes.
- That will allow us to expose defaults via OpenAPI.
We do not want to introduce the concept of resource versioning. I.e. a resource would also persist its version and the model layer would based on that need to resolve the defaults at runtime.
- This would mean lots of changes would need to be made to the model layer, significantly increasing the implementation effort while adding complexity to the Keycloak logic.
We want to support interchangeable usage of different API versions on a single resource. E.g. a Client created through API v2 would be accessible through v1.
- This is to allow seamless migration to new API versions while keeping the possibility to downgrade if the new (preview) version is not working well for the user.
- Defaults would be persisted based on the API version that persisted the resource. E.g. a Client created via v1, and later updated (PUT) via v2 will have v2 defaults, and vice versa.
- Keycloak internally doesn't differentiate between the versions, it will use whatever defaults were persisted.

Cons

The most prominent downside of persisting defaults is it would not be possible to GET a resource without the defaults (as it was suggested by the former design proposal).

This mostly affects the declarative/reconciling scenarios where the client wants to compare the actual and desired state. However, we believe this is not strictly necessary. The client can simply do PUT rightaway (instead of doing GET and the comparison before that). This assumes that if a resource is declaratively managed, there's only a single actor for a given resource instance. In other words, if e.g. a Client is managed via an Operator CR, it won't be possible to mutate it via other actors like Admin UI. This will be enforced via Fine Grained permissions.

Another affected area is user UX. It is very confusing (especially in the CLI scenarios) that when a resource is created only with a handful of fields, it suddenly has many more fields due to the defaults after it's created. This might be solved though, e.g. by tracking the default fields so that they are excluded when doing GET. However, this adds some complexity and considering the limited scenarios that would benefit from it, it doesn't seem really worth it.

See the discussion in #39547 for more context.

2 replies

slaskawi Jun 2, 2025
Author

Fully agree! Great write-up @vmuzikar !

jbman Aug 21, 2025

In #40145 it is suggested to use null values as a way to mean "use default":

if a field is set to null in a PUT or POST, it will be pruned and subject to defaulting.

That a default was requested by the API client should also be persisted and stay this way. There don't need to be guarantees that the effective default stays the same, when the client sends null (use current default). The effective default can be changed by migrations, but therefor it is essential to preserve if the client is happy with "some" default or if wants some specific configuration value.

The effective configuration value can also be persisted. It can be returned to clients when an extra parameter is provided (named "runtime" in the proposal above, however I would name it "effective"). But please note that this would be an implementation detail and it is not needed that an effective configuration is persisted.

The Defaults could be published via own API resource including metadata like "default applied at creation" or "default at runtime if not specified by persisted configuration".

Summary:

"Use default" should be provide as a option. If a client makes use of this, it should be preserved (not overwritten by an effective default).
The effective configuration value can persisted at creation time alongside in addition to the information what was requested (this is an implementation option, maybe no need to unify this across resources which can be configured)

Navigation Menu

Repository navigation

API Default Values Principles #38551

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

API Default Values Principles #38551

Uh oh!

slaskawi Mar 31, 2025

Summary

Proposed API Behavior

Ephemeral Default Values

Alternatives Considered

References

Replies: 2 comments · 2 replies

Uh oh!

vmuzikar May 16, 2025 Collaborator

Uh oh!

vmuzikar May 29, 2025 Collaborator

Updated Defaults proposal

Cons

Uh oh!

slaskawi Jun 2, 2025 Author

Uh oh!

Uh oh!

jbman Aug 21, 2025

slaskawi
Mar 31, 2025

Replies: 2 comments 2 replies

vmuzikar
May 16, 2025
Collaborator

vmuzikar
May 29, 2025
Collaborator

slaskawi Jun 2, 2025
Author