HTTP verb handling and other basic request response behaviors for the next Admin Api #39072

shawkins · 2025-04-17T21:37:00Z

shawkins
Apr 17, 2025
Collaborator

To facilitate more discussion we wanted to post some high-level goals for basic API functioning. Please let us know if you have thoughts or concerns as we continue to flesh out the full proposal.

GET
- Idempotent
- Get 1 (items/id) or more (items) results
- We'll make a distinction between declarative (GET what you PUT) vs runtime mode (GET everything including defaults, status information, and possibly a normalized version)
- Pagination - TBD (lot's of variations in the controls, consistency requirements, etc. to consider here)
- Filtering & Projection - TBD as much as possible should follow a standard or defacto standard. The current admin apis having unclear rules about what query parameters take precidence or what syntax query strings should be should be avoided. We'll try to work up proposals showing GraphQL or pragmatic choices of the Kube api-server.
- Responses (fundamental):
  - 200 OK - along with the resource(s). TODO on the particulars of the list format.
  - 400 Bad Request - wrong query params, …
  - 404 Not Found
DELETE
- Idempotent
- Delete one or more entities
- Filtering should support the same filtering as GET
- Cascading deletion TBD
- Delayed deletion TBD
- Archiving or tombstoning TBD
- Responses (fundamental):
  - 204 No Content - Alternatively support 200 / 202 - which could also return the last known state(s)
  - 400 Bad Request
  - 404 Not Found - if a single entity is not found
POST
- Not Idempotent
- Create a single entity or trigger an action (e.g. LDAP sync)
- If the entity already exists, return HTTP 409 Conflict
- Responses (fundamental):
  - 201 Created - along with the created resource
  - 400 Bad Request
  - 404 Not Found - should inticate path is no valid
  - 409 Conflict
PUT
- Nominally idempotent
- Update a single entity via overwriting the whole entity
- Will not support any PATCH semantics (which was confusing with some of the older admin api methods)
- Possibly create an entity if it does not exist
- Responses (fundamental):
  - 200 OK - along with the updated entity
  - ?? 201 Created - (at least we’d know if it existed or not - but it might break the idempotency) - along with the created entity
  - 400 Bad Request
  - 404 Not Found
PATCH
- Nominally Idempotent
- Update only a part of an entity
- Should not be viewed as distinct from PUT, but rather a composite operation. That is the server will logically GET the specified entity, apply the patch, then PUT the result. The implementation may be streamlined if possible, but the logical operation must remain consistent with the composite operation. There are more complicated systems, such as kubernetes server side apply (SSA), that still fits this high-level description but typically involves fully specifying the state you want and also introduces concepts such as field ownership. It’s not clear if we’ll need such concepts.
- Could initially support JSON Patch The biggest drawbacks are verbosity and it generally requires the client to GET the resource first.
- Additional well-defined patch types would be supported via different content types.
- Responses (fundamental):
  - 200 OK - along with the updated entity
  - ?? 201 Created - (at least we’d know if it existed or not - but it might break the idempotency) - along with the created entity
  - 400 Bad Request - In particular if the patch could not be applied
  - 404 Not Found
OPTIONS
- Idempotent
- Get permitted communication options (verbs) + CORS preflight
- Responses (fundamental):
  - 200 OK
  - 404 Not Found

Other API Characteristics

Authorization Results
- Course grained - 403 response codes
- Finer grained - Additional filtering and projection applied
Optimistic Locking
- This was brought up early on and is a cross-cutting concern for all the operations.
- Revisioning unfortunately can be quite complex - at the very least there is a desire for us to support optimistic locking. Locking is also more complicated when dealing with composite or aggregate entities as each sub-entity has its own logical revision
  they may be required to carry that metadata inline.
We're planning on making the declarative api uni-directional. Once a specific state has been declared it should not be alterable via other mechansims, such as the admin console.
There will be metadata facilities and OpenApi specifications - there may even be the need for resource level versioning

Additional Concepts

WebSockets
- If we want to implement more efficient long-running interactions with clients. However they do not fit the verb request response model.
- Supporting large lists of results via a WebSocket would generally be preferred to indefinitely writing to an HTTP body
  Also supporting the watching of resource changes would be better supported via a WebSocket.
GraphQL over HTTP
- GET what you want
- Projection: either from a single entity or from an aggregate root
- Allows for a more bespoke API - easily add specific mutations
- Simplified searching / filtering
- Quarkus supports GraphQL
- Recommended to end endpoint path by /graphql
- Request parameters:
  - Query (required)
- Media types
  - Request - application/json
  - Response - application/graphql-response+json or application/json (support legacy clients)
- Already some community interest: https://www.reddit.com/r/KeyCloak/comments/1g5x9d6/announcing_keycloakgraphql/
- Challenges:
  - No default handling for things like optimistic locking - it must be thought out and exposed on the operations / entities.
- Examples:

query getClient {
    client(clientId: xxxx) {
        name,
        description,
        protocolMappers {
	name,
	protocol
 }
    }
}

#JSON

{
  "query": "query getClient($clientId: ID!) { client(clientId: $clientId) { name description protocolMappers { name protocol } } }",
  "variables": {
    "clientId": "xxxx"
  }
}

Standalone kube api-server
- This is a possibility we could reuse the kube api-server for the purposes of our declarative api - or at the very least this could provide a thought exercise for an architecture where the there is a configurable declarative store / api-server.
- Main motivators:
  - We seem to want REST endpoints similar to the api-server, and want many of the features that it supports, such as locking/revisioning.
  - Decouples the declarative API from Keycloak core - the server would effectively act like an operator to the declarative state.
  - Could potentially have the option of working directly against the kube api server when deployed on Kubernetes
- This could either be a stand-alone api-server running similarly to how it runs in envtest / jenvtest or a custom api-server.
- Simple standalone api-server
  - Benefits:
    - Simplicity - would work at the level of a CRD.
  - Challenges:
    - Storage is a separate etcd store - it’s not clear how we would promote the management of that.
- Custom api-server
  - Benefits:
    - https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#advanced-features-and-flexibility
  - Challenges:
    - Supportability. While the main api-server is well supported, supporting a custom one may not be in IBM / Red Hat’s interest.
    - The effort for customization - see https://github.com/kubernetes/sample-apiserver
    - Implies we’d need go binding for types as well
    - Would mean that any non-default endpoints would require implementation in go, or would have to be done as part of proxying the api server
    - Would still be a separate process. There is a possibility it could reuse the main database. Currently only a mysql example is shown, but there are go drivers for most of our supported databases. The database storage doesn’t appear at first glance to be flexible - reusing internal table structures would be unlikely.

Navigation Menu

Repository navigation

HTTP verb handling and other basic request response behaviors for the next Admin Api #39072

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

HTTP verb handling and other basic request response behaviors for the next Admin Api #39072

Uh oh!

shawkins Apr 17, 2025 Collaborator

Replies: 0 comments

shawkins
Apr 17, 2025
Collaborator