Apache Iceberg Configuration API API

openapi: 3.1.1
info:
  title: Apache Iceberg REST Catalog Catalog API Configuration API API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1
  description: Defines the specification for the first version of the REST Catalog API. Implementations should ideally support all Iceberg table spec versions.
servers:
- url: '{scheme}://{host}/{basePath}'
  description: Server URL when the port can be inferred from the scheme
  variables:
    scheme:
      description: The scheme of the URI, either http or https.
      default: https
    host:
      description: The host address for the specified server
      default: localhost
    basePath:
      description: Optional prefix to be appended to all routes
      default: ''
- url: '{scheme}://{host}:{port}/{basePath}'
  description: Generic base server URL, with all parts configurable
  variables:
    scheme:
      description: The scheme of the URI, either http or https.
      default: https
    host:
      description: The host address for the specified server
      default: localhost
    port:
      description: The port used when addressing the host
      default: '443'
    basePath:
      description: Optional prefix to be appended to all routes
      default: ''
security:
- OAuth2:
  - catalog
- BearerAuth: []
tags:
- name: Configuration API
paths:
  /v1/config:
    get:
      tags:
      - Configuration API
      summary: Apache Iceberg List All Catalog Configuration Settings
      operationId: getConfig
      parameters:
      - name: warehouse
        in: query
        required: false
        schema:
          type: string
        description: Warehouse location or identifier to request from the service
        example: example-value
      description: ' All REST clients should first call this route to get catalog configuration properties from the server to configure the catalog and its HTTP client. Configuration from the server consists of two sets of key/value pairs.

        - defaults -  properties that should be used as default configuration; applied before client configuration

        - overrides - properties that should be used to override client configuration; applied after defaults and client configuration


        Catalog configuration is constructed by setting the defaults, then client- provided configuration, and finally overrides. The final property set is then used to configure the catalog.


        For example, a default configuration property might set the size of the client pool, which can be replaced with a client-specific setting. An override might be used to set the warehouse location, which is stored on the server rather than in client configuration.


        Common catalog configuration settings are documented at https://iceberg.apache.org/docs/latest/configuration/#catalog-properties


        The catalog configuration also holds an optional `endpoints` field that contains information about the endpoints supported by the server. If a server does not send the `endpoints` field, a default set of endpoints is assumed:

        - GET /v1/{prefix}/namespaces

        - POST /v1/{prefix}/namespaces

        - GET /v1/{prefix}/namespaces/{namespace}

        - DELETE /v1/{prefix}/namespaces/{namespace}

        - POST /v1/{prefix}/namespaces/{namespace}/properties

        - GET /v1/{prefix}/namespaces/{namespace}/tables

        - POST /v1/{prefix}/namespaces/{namespace}/tables

        - GET /v1/{prefix}/namespaces/{namespace}/tables/{table}

        - POST /v1/{prefix}/namespaces/{namespace}/tables/{table}

        - DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}

        - POST /v1/{prefix}/namespaces/{namespace}/register

        - POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics

        - POST /v1/{prefix}/tables/rename

        - POST /v1/{prefix}/transactions/commit '
      responses:
        200:
          description: Server specified configuration values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogConfig'
              example:
                overrides:
                  warehouse: s3://bucket/warehouse/
                defaults:
                  clients: '4'
                idempotency-key-lifetime: PT30M
                endpoints:
                - GET /v1/{prefix}/namespaces/{namespace}
                - GET /v1/{prefix}/namespaces
                - POST /v1/{prefix}/namespaces
                - GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
                - GET /v1/{prefix}/namespaces/{namespace}/views/{view}
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Warehouse provided in the `warehouse` query parameter is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchWarehouseExample:
                  $ref: '#/components/examples/NoSuchWarehouseError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    ServiceUnavailableResponse:
      description: 'The service is not ready to handle the request, request could have been partially processed.

        The service may additionally send a Retry-After header to indicate when to retry, a non idempotent request should only be retried by the client when the Retry-After header is present.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Slow down
              type: SlowDownException
              code: 503
    ForbiddenResponse:
      description: Forbidden. Authenticated user does not have the necessary permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Not authorized to make this request
              type: NotAuthorizedException
              code: 403
    AuthenticationTimeoutResponse:
      description: This is an optional status response type that the REST Catalog can issue when the token has expired. The client MAY request a new access token and retry the request. 401 UnauthorizedResponse SHOULD be preferred over this response type on token expiry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Credentials have timed out
              type: AuthenticationTimeoutException
              code: 419
    UnauthorizedResponse:
      description: Unauthorized. The REST Catalog SHOULD respond with the 401 UnauthorizedResponse when the access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Not authorized to make this request
              type: NotAuthorizedException
              code: 401
    BadRequestErrorResponse:
      description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Malformed request
              type: BadRequestException
              code: 400
    ServerErrorResponse:
      description: A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example:
            error:
              message: Internal Server Error
              type: InternalServerError
              code: 500
  examples:
    NoSuchWarehouseError:
      summary: The requested warehouse does not exist
      value:
        error:
          message: The given warehouse does not exist
          type: NoSuchWarehouseException
          code: 404
  schemas:
    CatalogConfig:
      type: object
      description: Server-provided configuration for the catalog.
      required:
      - defaults
      - overrides
      properties:
        overrides:
          type: object
          additionalProperties:
            type: string
          description: Properties that should be used to override client configuration; applied after defaults and client configuration.
        defaults:
          type: object
          additionalProperties:
            type: string
          description: Properties that should be used as default configuration; applied before client configuration.
        endpoints:
          type: array
          items:
            type: string
          description: A list of endpoints that the server supports. The format of each endpoint must be "<HTTP verb> <resource path from OpenAPI REST spec>". The HTTP verb and the resource path must be separated by a space character.
          example:
          - GET /v1/{prefix}/namespaces/{namespace}
          - GET /v1/{prefix}/namespaces
          - POST /v1/{prefix}/namespaces
          - GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
          - GET /v1/{prefix}/namespaces/{namespace}/views/{view}
        idempotency-key-lifetime:
          type: string
          format: duration
          description: Client reuse window for an Idempotency-Key (ISO-8601 duration, e.g., PT30M, PT24H). Interpreted as the maximum time from the first submission using a key to the last retry during which a client may reuse that key. Servers SHOULD accept retries for at least this duration and MAY include a grace period to account for delays/clock skew. Clients SHOULD NOT reuse an Idempotency-Key after this window elapses; they SHOULD generate a new key for any subsequent attempt. Presence of this field indicates the server supports Idempotency-Key semantics for mutation endpoints. If absent, clients MUST assume idempotency is not supported.
          example: PT30M
    ErrorModel:
      type: object
      description: JSON error payload returned in a response with further details on the error
      required:
      - message
      - type
      - code
      properties:
        message:
          type: string
          description: Human-readable error message
        type:
          type: string
          description: Internal type definition of the error
          example: NoSuchNamespaceException
        code:
          type: integer
          minimum: 400
          maximum: 600
          description: HTTP response code
          example: 404
        stack:
          type: array
          items:
            type: string
    IcebergErrorResponse:
      description: JSON wrapper for all error responses (non-2xx)
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorModel'
      additionalProperties: false
      example:
        error:
          message: The server does not support this operation
          type: UnsupportedOperationException
          code: 406
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'This scheme is used for OAuth2 authorization.


        For unauthorized requests, services should return an appropriate 401 or 403 response. Implementations must not return altered success (200) responses when a request is unauthenticated or unauthorized.

        If a separate authorization server is used, substitute the tokenUrl with the full token path of the external authorization server, and use the resulting token to access the resources defined in the spec.'
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth/tokens
          scopes:
            catalog: Allows interacting with the Config and Catalog APIs
    BearerAuth:
      type: http
      scheme: bearer