API Evangelist enhancements for the Lakekeeper Management API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Lakekeeper Management API
  version: 1.0.0
extends: openapi/lakekeeper-management-api-openapi.yml
x-generated: '2026-08-27'
x-method: generated
x-source: >-
  Derived from openapi/lakekeeper-management-api-openapi.yml plus the provider documentation at
  docs.lakekeeper.io. Captures API Evangelist annotations only; the original specification is never mutated.
actions:
- target: $.info
  description: >-
    The spec is generated by utoipa at build time and stamps info.version 0.0.0, which does not identify the
    release it describes. Record the release this document was harvested from, and the fact that the running
    server serves a version-accurate Swagger-UI.
  update:
    x-harvested-release: v0.13.3
    x-harvested-from: https://docs.lakekeeper.io/docs/latest/api/management-open-api.yaml
    x-harvested-on: '2026-08-27'
    x-version-accurate-reference: /swagger-ui/#/ on the running server
    x-license-url: https://docs.lakekeeper.io/about/license/
- target: $.servers
  description: >-
    The templated server correctly says the host is deployment-specific. Annotate the path prefix and the
    documented default so a client knows what to substitute.
  update:
  - x-default-development-url: http://localhost:8181
    x-path-prefix: /management/v1
    x-deployment: self-hosted — the host is the operator's, there is no vendor-operated base URL
- target: $.components.securitySchemes.BearerAuth
  description: Record where the token comes from, since the scheme itself only says "bearer JWT".
  update:
    x-token-issuer: >-
      An external OIDC provider configured with LAKEKEEPER__OPENID_PROVIDER_URI (or several, via
      LAKEKEEPER__OPENID_PROVIDERS since v0.13.0). The provider must expose /.well-known/openid-configuration
      with jwks_uri and issuer.
    x-audience-validation: >-
      Set LAKEKEEPER__OPENID_AUDIENCE so tokens minted for other applications on the same IdP cannot be replayed.
    x-alternative: Kubernetes service-account tokens are also accepted.
    x-docs: https://docs.lakekeeper.io/docs/latest/authentication/
- target: $.paths['/management/v1/warehouse/{warehouse_id}/deleted-tabulars/undrop'].post
  description: >-
    Mark the reversal path and its window explicitly. Reversibility is invisible in the raw spec — the operation
    reads as an ordinary POST — yet whether a drop can be taken back is what an agent needs to know BEFORE it acts.
  update:
    x-reversal-of: dropTable / dropView (Iceberg REST Catalog API)
    x-window: >-
      Warehouse-configured. TabularDeleteProfile is either type `hard` (no window, irreversible) or type `soft`
      with a required expiration-seconds. The delay is fixed at the moment of dropping; changing the Warehouse
      setting later affects only newly dropped tables.
    x-window-source: https://docs.lakekeeper.io/docs/latest/concepts/#soft-deletion
    x-precondition: Read get_warehouse first — a Warehouse on the hard delete profile has no reversal path.
- target: $.paths['/management/v1/warehouse/{warehouse_id}'].delete
  description: Flag the irreversible operations so an agent does not treat them like the reversible ones.
  update:
    x-irreversible: true
    x-safer-alternative: >-
      deactivate_warehouse (POST /management/v1/warehouse/{warehouse_id}/deactivate) takes a Warehouse out of
      service reversibly; activate_warehouse restores it.
- target: $.paths['/management/v1/project'].delete
  description: Flag the irreversible project deletion.
  update:
    x-irreversible: true
    x-note: No undelete endpoint exists for a Project.
- target: $.components.schemas.IcebergErrorResponse
  description: >-
    Record that this is the Iceberg REST error wrapper and explicitly NOT RFC 9457, so a client does not try to
    parse it as application/problem+json.
  update:
    x-error-format: iceberg-rest-error-wrapper
    x-rfc9457: false
    x-media-type: application/json
    x-catalog: errors/lakekeeper-problem-types.yml
    x-403-caveat: >-
      Lakekeeper does not always return 404 for missing objects. A 403 with apparently correct grants very often
      means the object does not exist — an anti-enumeration measure, documented at
      https://docs.lakekeeper.io/docs/latest/gotchas/.
- target: $.paths['/management/v1/warehouse'].get
  description: >-
    Annotate the pagination contract, which the parameters describe structurally but do not explain.
  update:
    x-pagination-style: opaque-cursor
    x-pagination-request: pageToken + pageSize
    x-pagination-response-field: next-page-token
    x-return-all-configuration: >-
      LAKEKEEPER__PAGINATION_SIZE_MAX=4294967295 restores the Iceberg spec's return-everything behaviour when
      pageToken is unset.
- target: $.tags
  description: >-
    The Management API declares a single blanket 4XX response on 81 operations. Record that as a known contract
    gap at document level rather than annotating every operation.
  update:
  - x-contract-gap: >-
      81 of 120 operations declare only a catch-all `4XX` response instead of enumerating 400/403/404/409, so an
      agent cannot tell from the contract which client errors are reachable on a given call.