#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

---
paths:
  /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables:
    parameters:
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/namespace'

    get:
      tags:
        - Generic Table API
      summary: List all generic tables identifiers underneath a given namespace
      description: Return all generic table identifiers under this namespace
      operationId: listGenericTables
      parameters:
        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
      responses:
        200:
          $ref: '#/components/responses/ListGenericTablesResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchNamespaceError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

    post:
      tags:
        - Generic Table API
      summary: Create a generic table under the given namespace
      description:
        Create a generic table under the given namespace, and return the created table information as a response.
      operationId: createGenericTable
      parameters:
        - $ref: '#/components/parameters/polaris-generic-table-data-access'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGenericTableRequest'
      responses:
        200:
          $ref: '#/components/responses/CreateGenericTableResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchNamespaceError'
        409:
          description: Conflict - The table already exists under the given namespace
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableAlreadyExists:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/TableAlreadyExistsError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

  /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/{generic-table}:
    parameters:
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/namespace'
      - $ref: '#/components/parameters/generic-table'

    get:
      tags:
        - Generic Table API
      summary: Load a generic table under the given namespace from the catalog
      operationId: loadGenericTable
      description:
        Load a generic table from the catalog under the given namespace.
      
        The response contains all table information passed during create.

      parameters:
        - $ref: '#/components/parameters/polaris-generic-table-data-access'
      responses:
        200:
          $ref: '#/components/responses/LoadGenericTableResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description:
            Not Found - NoSuchTableError, generic table to load does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableToLoadDoesNotExist:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

    delete:
      tags:
        - Generic Table API
      summary: Drop a generic table under the given namespace from the catalog
      operationId: dropGenericTable
      description: Remove a table under the given namespace from the catalog
      responses:
        204:
          description: Success, no content
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description:
            Not Found - NoSuchTableError, Generic table to drop does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableToDeleteDoesNotExist:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

components:
  parameters:
    generic-table:
      name: generic-table
      in: path
      description: A generic table name
      required: true
      schema:
        type: string
      example: "sales"

    polaris-generic-table-data-access:
      name: Polaris-Generic-Table-Access-Delegation
      in: header
      description: >
        Optional header indicating that the client supports delegated access
        using a specific mechanism. If the header is present, the server must
        either provide access using the requested mechanism or fail the request.
        If `vended-credentials` is specified, the server must return scoped
        storage credentials in the `storage-access-configs` field of the response.
      required: false
      schema:
        type: string
        enum:
          - vended-credentials
      style: simple
      explode: false
      example: "vended-credentials"

  schemas:
    CreateGenericTableRequest:
      type: object
      required:
        - name
        - format
      properties:
        name:
          type: string
        format:
          type: string
        base-location:
          type: string
        doc:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string

    GenericTable:
      type: object
      description: >
        Generic Table information.
        
        - `name` (REQUIRED): name for the generic table
        
        - `format` (REQUIRED): format for the generic table, i.e. "delta", "csv"
        
        - `base-location` (OPTIONAL): table base location in URI format. For example: s3://<my-bucket>/path/to/table.
          - The table base location is a location that includes all files for the table.
          - A table with multiple disjoint locations (i.e. containing files that are outside the configured base location) is not compliant with the current generic table support in Polaris.
          - If no location is provided, clients or users are responsible for managing the location.
        
        - `properties` (OPTIONAL): properties for the generic table passed on creation
        
        - `doc` (OPTIONAL): comment or description for the generic table
      required:
        - name
        - format
      properties:
        name:
          type: string
        format:
          type: string
        base-location:
          type: string
        doc:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string

    LoadGenericTableResponse:
      description: Result used when a table is successfully loaded.
      type: object
      required:
        - table
      properties:
        table:
          $ref: '#/components/schemas/GenericTable'
        storage-access-configs:
          type: array
          description: |
            Storage configurations required to access the table, encompassing both credentials and other necessary 
            settings for storage access, such as the client region for S3.
          items:
            $ref: '#/components/schemas/StorageAccessConfig'


    ListGenericTablesResponse:
      type: object
      properties:
        next-page-token:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
        identifiers:
          type: array
          uniqueItems: true
          items:
            $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/TableIdentifier'


    StorageAccessConfig:
      type: object
      required:
        - prefix
        - config
      properties:
        prefix:
          type: string
          description: Indicates a storage location prefix where the configuration is relevant. Clients should choose the most 
            specific prefix (by selecting the longest common prefix) if several configurations of the same type are available.
            If multiple configurations share the same longest matching prefix, the client may select any of them. However, 
            a server should avoid generating multiple configurations for the same prefix.
        config:
          type: object
          description: |
            Storage access configurations for S3, GCP GCS, and Azure ADLS are supported. The following outlines 
            the currently supported configuration options:
              
            ## S3 Configurations
              
            The following configurations should be respected when working with tables stored on S3, including AWS S3, S3-Compatible systems:
              - `s3.access-key-id`: id for credentials that provide access to the data in S3
              - `s3.secret-access-key`: secret for credentials that provide access to data in S3
              - `s3.session-token`: if present, this value should be used for as the session token
              - `s3.session-token-expires-at-ms`: the time the aws session token expires, in milliseconds
              - `s3.client.region`: region to configure client for making requests to S3
              - `s3.client.refresh-credentials-endpoint`: the endpoint to load vended credentials for a table from the catalog
              
            ## GCP GCS Configurations
            
            The following configurations should be respected when working with tables stored in GCP GCS:
              - `gcs.oauth2.token`: the gcs scoped access token
              - `gcs.oauth2.token-expires-at`: the time the gcs access token expires, in milliseconds
              - `gcs.oauth2.refresh-credentials-endpoint`: the endpoint to load vended credentials for a table from the catalog
            
            ## AZURE ADLS Configuration
            
            The following configurations should be respected when working with tables stored in AZURE ADLS:
              - `adls.sas-token.<hostname>`: an azure shared access signature token
              - `adls.sas-token-expires-at-ms.<hostname>`: the expiration time for the access token, in milliseconds
              - `adls.refresh-credentials-endpoint`: the endpoint to load vended credentials for a table from the catalog

          additionalProperties:
            type: string

  responses:

    LoadGenericTableResponse:
      description: Table result if successfully load a generic table.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoadGenericTableResponse'


    CreateGenericTableResponse:
      description: Table result if successfully created a generic table.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoadGenericTableResponse'


    ListGenericTablesResponse:
      description: List of generic table identifiers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListGenericTablesResponse'