Apache Iceberg REST Catalog API

openapi: 3.1.1
info:
  title: Apache Iceberg REST Catalog 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: ""
# All routes are currently configured using an Authorization header.
security:
- OAuth2: [catalog]
- BearerAuth: []

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.\n- defaults -  properties that should be used as default configuration; applied before client configuration\n- overrides - properties that should be used to override
        client configuration; applied after defaults and client configuration\n\nCatalog 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.\n\nFor 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.\n\nCommon catalog configuration settings are documented at https://iceberg.apache.org/docs/latest/configuration/#catalog-properties\n\
        \nThe 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:\n- GET /v1/{prefix}/namespaces\n- POST /v1/{prefix}/namespaces\n- GET /v1/{prefix}/namespaces/{namespace}\n- DELETE /v1/{prefix}/namespaces/{namespace}\n- POST /v1/{prefix}/namespaces/{namespace}/properties\n\
        - GET /v1/{prefix}/namespaces/{namespace}/tables\n- POST /v1/{prefix}/namespaces/{namespace}/tables\n- GET /v1/{prefix}/namespaces/{namespace}/tables/{table}\n- POST /v1/{prefix}/namespaces/{namespace}/tables/{table}\n\
        - DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}\n- POST /v1/{prefix}/namespaces/{namespace}/register\n- POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics\n- POST /v1/{prefix}/tables/rename\n\
        - 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
  /v1/oauth/tokens:

    post:
      tags:
      - OAuth2 API
      summary: Apache Iceberg Get a Token Using an OAuth2 Flow (DEPRECATED for REMOVAL)
      deprecated: true
      operationId: getToken
      description: "The `oauth/tokens` endpoint is **DEPRECATED for REMOVAL**. It is _not_ recommended to implement this endpoint, unless you are fully aware of the potential security implications.\nAll
        clients are encouraged to explicitly set the configuration property `oauth2-server-uri` to the correct OAuth endpoint.\nDeprecated since Iceberg (Java) 1.6.0. The endpoint and related types will
        be removed from this spec in Iceberg (Java) 2.0.\nSee [Security improvements in the Iceberg REST specification](https://github.com/apache/iceberg/issues/10537)\n\nExchange credentials for a token
        using the OAuth2 client credentials flow or token exchange.\n\nThis endpoint is used for three purposes -\n1. To exchange client credentials (client ID and secret) for an access token This uses
        the client credentials flow.\n2. To exchange a client token and an identity token for a more specific access token This uses the token exchange flow.\n3. To exchange an access token for one with
        the same claims and a refreshed expiration period This uses the token exchange flow.\n\nFor example, a catalog client may be configured with client credentials from the OAuth2 Authorization flow.
        This client would exchange its client ID and secret for an access token using the client credentials request with this endpoint (1). Subsequent requests would then use that access token.\n\nSome
        clients may also handle sessions that have additional user context. These clients would use the token exchange flow to exchange a user token (the \"subject\" token) from the session for a more specific
        access token for that user, using the catalog's access token as the \"actor\" token (2). The user ID token is the \"subject\" token and can be any token type allowed by the OAuth2 token exchange
        flow, including a unsecured JWT token with a sub claim. This request should use the catalog's bearer token in the \"Authorization\" header.\n\nClients may also use the token exchange flow to refresh
        a token that is about to expire by sending a token exchange request (3). The request's \"subject\" token should be the expiring token. This request should use the subject token in the \"Authorization\"\
        \ header."
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
      responses:
        200:
          $ref: '#/components/responses/OAuthTokenResponse'
        400:
          $ref: '#/components/responses/OAuthErrorResponse'
        401:
          $ref: '#/components/responses/OAuthErrorResponse'
        5XX:
          $ref: '#/components/responses/OAuthErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces:
    parameters:
    - $ref: '#/components/parameters/prefix'

    get:
      tags:
      - Catalog API
      summary: Apache Iceberg List Namespaces, Optionally Providing a Parent Namespace to List Underneath
      description: List all namespaces at a certain level, optionally starting from a given parent namespace. If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would 
        translate into `GET /namespaces?parent=accounting` and must return a namespace, ["accounting", "tax"] only. Using 'SELECT NAMESPACE IN accounting.tax' would translate into `GET 
        /namespaces?parent=accounting%1Ftax` and must return a namespace, ["accounting", "tax", "paid"]. If `parent` is not provided, all top-level namespaces should be listed.
      operationId: listNamespaces
      parameters:
      - $ref: '#/components/parameters/page-token'
      - $ref: '#/components/parameters/page-size'
      - name: parent
        in: query
        description: An optional namespace, underneath which to list namespaces. If not provided, all top-level namespaces should be listed. For backward compatibility, empty string is treated as 
          absent for now. If parent is a multipart namespace, the parts must be separated by the namespace separator as indicated via the /config override `namespace-separator`, which defaults to the 
          unit separator `0x1F` byte (url encoded `%1F`). To be compatible with older clients, servers must use both the advertised separator and `0x1F` as valid separators when decoding namespaces. 
          The `namespace-separator` should be provided in a url encoded form.
        required: false
        schema:
          type: string
        example: "accounting%1Ftax"
      responses:
        200:
          $ref: '#/components/responses/ListNamespacesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace provided in the `parent` query parameter is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Catalog API
      summary: Apache Iceberg Create a Namespace
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: Create a namespace, with an optional set of properties. The server might also add properties, such as `last_modified_time` etc.
      operationId: createNamespace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespaceRequest'
            examples:
              createNamespaceRequestExample:
                summary: Default createNamespace request
                x-microcks-default: true
                value:
                  properties: &id001 {"owner": "Hank Bendickson"}
      responses:
        200:
          $ref: '#/components/responses/CreateNamespaceResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        409:
          description: Conflict - The namespace already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceAlreadyExists:
                  $ref: '#/components/examples/NamespaceAlreadyExistsError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces/{namespace}:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'

    get:
      tags:
      - Catalog API
      summary: Apache Iceberg Load the Metadata Properties for a Namespace
      operationId: loadNamespaceMetadata
      description: Return all stored metadata properties for a given namespace
      responses:
        200:
          $ref: '#/components/responses/GetNamespaceResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    head:
      tags:
      - Catalog API
      summary: Apache Iceberg Check if a Namespace Exists
      operationId: namespaceExists
      description: Check if a namespace exists. The response does not contain a body.
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Catalog API
      summary: Apache Iceberg Drop a Namespace from the Catalog. Namespace Must Be Empty.
      operationId: dropNamespace
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace to delete does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        409:
          description: Not Empty - Namespace to delete is not empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotEmptyExample:
                  $ref: '#/components/examples/NamespaceNotEmptyError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces/{namespace}/properties:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'

    post:
      tags:
      - Catalog API
      summary: Apache Iceberg Set or Remove Properties on a Namespace
      operationId: updateProperties
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: "Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update.\nProperties that are not in the request
        are not modified or removed by this call.\nServer implementations are not required to support namespace properties."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
            examples:
              UpdateAndRemoveProperties:
                $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
      responses:
        200:
          $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        422:
          description: Unprocessable Entity - A property key was included in both `removals` and `updates`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                UnprocessableEntityDuplicateKey:
                  $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces/{namespace}/tables:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'

    get:
      tags:
      - Catalog API
      summary: Apache Iceberg List All Table Identifiers Underneath a Given Namespace
      description: Return all table identifiers under this namespace
      operationId: listTables
      parameters:
      - $ref: '#/components/parameters/page-token'
      - $ref: '#/components/parameters/page-size'
      responses:
        200:
          $ref: '#/components/responses/ListTablesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Catalog API
      summary: Apache Iceberg Create a Table in the Given Namespace
      description: "Create a table or start a create transaction, like atomic CTAS.\n\nIf `stage-create` is false, the table is created immediately.\n\nIf `stage-create` is true, the table is not created,
        but table metadata is initialized and returned. The service should prepare as needed for a commit to the table commit endpoint to complete the create transaction. The client uses the returned metadata
        to begin a transaction. To commit the transaction, the client sends all create and subsequent changes to the table commit route. Changes from the table create operation include changes like AddSchemaUpdate
        and SetCurrentSchemaUpdate that set the initial table state."
      operationId: createTable
      parameters:
      - $ref: '#/components/parameters/data-access'
      - $ref: '#/components/parameters/idempotency-key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
            examples:
              createTableRequestExample:
                summary: Default createTable request
                x-microcks-default: true
                value:
                  name: example-value
                  location: s3://my-bucket/warehouse
                  stage-create: true
                  properties: {}
      responses:
        200:
          $ref: '#/components/responses/CreateTableResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        409:
          description: Conflict - The table already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                TableAlreadyExists:
                  $ref: '#/components/examples/TableAlreadyExistsError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    - $ref: '#/components/parameters/data-access'
    post:
      tags:
      - Catalog API
      summary: Apache Iceberg Submit a Scan for Planning
      description: >
        Submits a scan for server-side planning.


        Point-in-time scans are planned by passing snapshot-id to identify the
        table snapshot to scan. Incremental scans are planned by passing both
        start-snapshot-id and end-snapshot-id. Requests that include both point
        in time config properties and incremental config properties are
        invalid. If the request does not include either incremental or
        point-in-time config properties, scan planning should produce a
        point-in-time scan of the latest snapshot in the table's main branch.


        Responses must include a valid status listed below. A "cancelled" status is considered invalid for this endpoint.

        - When "completed" the planning operation has produced plan tasks and
          file scan tasks that must be returned in the response (not fetched
          later by calling fetchPlanningResult)

        - When "submitted" the response must include a plan-id used to poll
          fetchPlanningResult to fetch the planning result when it is ready

        - When "failed" the response must be a valid error response

        The response for a "completed" planning operation includes two types of
        tasks (file scan tasks and plan tasks) and both may be included in the
        response. Tasks must not be included for any other response status.


        Responses that include a plan-id indicate that the service is holding
        state or performing work for the client.


        - Clients should use the plan-id to fetch results from
          fetchPlanningResult when the response status is "submitted"

        - Clients should inform the service if planning results are no longer
          needed by calling cancelPlanning. Cancellation is not necessary after
          fetchScanTasks has been used to fetch scan tasks for each plan task.
      operationId: planTableScan
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanTableScanRequest'
            examples:
              planTableScanRequestExample:
                summary: Default planTableScan request
                x-microcks-default: true
                value:
                  snapshot-id: 0
                  select: []
                  min-rows-requested: 6
                  case-sensitive: true
                  use-snapshot-schema: true
                  start-snapshot-id: 20
                  end-snapshot-id: 91
                  stats-fields: []
      responses:
        200:
          $ref: '#/components/responses/PlanTableScanResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    - $ref: '#/components/parameters/plan-id'
    - $ref: '#/components/parameters/data-access'

    get:
      tags:
      - Catalog API
      summary: Apache Iceberg Fetches the Result of Scan Planning for a Plan-id
      operationId: fetchPlanningResult
      description: >
        Fetches the result of scan planning for a plan-id.


        Responses must include a valid status

        - When "completed" the planning operation has produced plan-tasks and
          file-scan-tasks that must be returned in the response

        - When "submitted" the planning operation has not completed; the client
          should wait to call this endpoint again to fetch a completed response

        - When "failed" the response must be a valid error response

        - When "cancelled" the plan-id is invalid and should be discarded


        The response for a "completed" planning operation includes two types of
        tasks (file scan tasks and plan tasks) and both may be included in the
        response. Tasks must not be included for any other response status.
      responses:
        200:
          $ref: '#/components/responses/FetchPlanningResultResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                PlanIdDoesNotExist:
                  $ref: '#/components/examples/NoSuchPlanIdError'
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Catalog API
      summary: Apache Iceberg Cancels Scan Planning for a Plan-id
      operationId: cancelPlanning
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: >
        Cancels scan planning for a plan-id.


        This notifies the service that it can release resources held for the
        scan. Clients should cancel scans that are no longer needed, either
        while the plan-id returns a "submitted" status or while there are
        remaining plan tasks that have not been fetched.


        Cancellation is not necessary when

        - Scan tasks for each plan task have been fetched using fetchScanTasks

        - A plan-id has produced a "failed" or "cancelled" status from
          planTableScan or fetchPlanningResult
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                PlanIdDoesNotExist:
                  $ref: '#/components/examples/NoSuchPlanIdError'
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorR

# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apache-iceberg/refs/heads/main/openapi/apache-iceberg-rest-catalog-open-api.yaml