Release GA

releases/8.40/specifications/catalog-integration.yaml

@@ -0,0 +1,346 @@
+openapi: 3.0.0
+servers:
+- description: Snowflake REST Server
+  url: https://org-account.snowflakecomputing.com
+info:
+  version: 0.0.1
+  title: Snowflake Catalog Integration API
+  description: The Snowflake Catalog Integration API is a REST API that you can use
+    to access, update, and perform certain actions on Catalog Integration resource
+    in a Snowflake database.
+  contact:
+    name: Snowflake, Inc.
+    url: https://snowflake.com
+    email: [email protected]
+paths:
+  /api/v2/catalog-integrations:
+    get:
+      summary: List catalog integrations.
+      tags:
+      - catalog-integration
+      description: List catalog integrations.
+      operationId: listCatalogIntegrations
+      parameters:
+      - $ref: common.yaml#/components/parameters/like
+      responses:
+        '200':
+          description: successful
+          headers:
+            X-Snowflake-Request-ID:
+              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CatalogIntegration'
+        '202':
+          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
+        '400':
+          $ref: common.yaml#/components/responses/400BadRequest
+        '401':
+          $ref: common.yaml#/components/responses/401Unauthorized
+        '403':
+          $ref: common.yaml#/components/responses/403Forbidden
+        '404':
+          $ref: common.yaml#/components/responses/404NotFound
+        '405':
+          $ref: common.yaml#/components/responses/405MethodNotAllowed
+        '408':
+          $ref: common.yaml#/components/responses/408RequestTimeout
+        '409':
+          $ref: common.yaml#/components/responses/409Conflict
+        '410':
+          $ref: common.yaml#/components/responses/410Gone
+        '429':
+          $ref: common.yaml#/components/responses/429LimitExceeded
+        '500':
+          $ref: common.yaml#/components/responses/500InternalServerError
+        '503':
+          $ref: common.yaml#/components/responses/503ServiceUnavailable
+        '504':
+          $ref: common.yaml#/components/responses/504GatewayTimeout
+    post:
+      summary: Create a catalog integration.
+      tags:
+      - catalog-integration
+      description: Create a catalog integration.
+      operationId: createCatalogIntegration
+      parameters:
+      - $ref: common.yaml#/components/parameters/createMode
+      responses:
+        '200':
+          $ref: common.yaml#/components/responses/200SuccessResponse
+        '202':
+          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
+        '400':
+          $ref: common.yaml#/components/responses/400BadRequest
+        '401':
+          $ref: common.yaml#/components/responses/401Unauthorized
+        '403':
+          $ref: common.yaml#/components/responses/403Forbidden
+        '404':
+          $ref: common.yaml#/components/responses/404NotFound
+        '405':
+          $ref: common.yaml#/components/responses/405MethodNotAllowed
+        '408':
+          $ref: common.yaml#/components/responses/408RequestTimeout
+        '409':
+          $ref: common.yaml#/components/responses/409Conflict
+        '410':
+          $ref: common.yaml#/components/responses/410Gone
+        '429':
+          $ref: common.yaml#/components/responses/429LimitExceeded
+        '500':
+          $ref: common.yaml#/components/responses/500InternalServerError
+        '503':
+          $ref: common.yaml#/components/responses/503ServiceUnavailable
+        '504':
+          $ref: common.yaml#/components/responses/504GatewayTimeout
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CatalogIntegration'
+  /api/v2/catalog-integrations/{name}:
+    get:
+      summary: Fetch a catalog integration.
+      tags:
+      - catalog-integration
+      description: Fetch a catalog integration.
+      operationId: fetchCatalogIntegration
+      parameters:
+      - $ref: common.yaml#/components/parameters/name
+      responses:
+        '200':
+          description: successful
+          headers:
+            X-Snowflake-Request-ID:
+              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogIntegration'
+        '202':
+          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
+        '400':
+          $ref: common.yaml#/components/responses/400BadRequest
+        '401':
+          $ref: common.yaml#/components/responses/401Unauthorized
+        '403':
+          $ref: common.yaml#/components/responses/403Forbidden
+        '404':
+          $ref: common.yaml#/components/responses/404NotFound
+        '405':
+          $ref: common.yaml#/components/responses/405MethodNotAllowed
+        '408':
+          $ref: common.yaml#/components/responses/408RequestTimeout
+        '409':
+          $ref: common.yaml#/components/responses/409Conflict
+        '410':
+          $ref: common.yaml#/components/responses/410Gone
+        '429':
+          $ref: common.yaml#/components/responses/429LimitExceeded
+        '500':
+          $ref: common.yaml#/components/responses/500InternalServerError
+        '503':
+          $ref: common.yaml#/components/responses/503ServiceUnavailable
+        '504':
+          $ref: common.yaml#/components/responses/504GatewayTimeout
+    delete:
+      summary: Delete a catalog integration.
+      tags:
+      - catalog-integration
+      description: Delete a catalog integration.
+      operationId: deleteCatalogIntegration
+      parameters:
+      - $ref: common.yaml#/components/parameters/name
+      - $ref: common.yaml#/components/parameters/ifExists
+      responses:
+        '200':
+          $ref: common.yaml#/components/responses/200SuccessResponse
+        '202':
+          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
+        '400':
+          $ref: common.yaml#/components/responses/400BadRequest
+        '401':
+          $ref: common.yaml#/components/responses/401Unauthorized
+        '403':
+          $ref: common.yaml#/components/responses/403Forbidden
+        '404':
+          $ref: common.yaml#/components/responses/404NotFound
+        '405':
+          $ref: common.yaml#/components/responses/405MethodNotAllowed
+        '408':
+          $ref: common.yaml#/components/responses/408RequestTimeout
+        '409':
+          $ref: common.yaml#/components/responses/409Conflict
+        '410':
+          $ref: common.yaml#/components/responses/410Gone
+        '429':
+          $ref: common.yaml#/components/responses/429LimitExceeded
+        '500':
+          $ref: common.yaml#/components/responses/500InternalServerError
+        '503':
+          $ref: common.yaml#/components/responses/503ServiceUnavailable
+        '504':
+          $ref: common.yaml#/components/responses/504GatewayTimeout
+components:
+  schemas:
+    CatalogIntegration:
+      type: object
+      description: Catalog integration
+      properties:
+        name:
+          type: string
+          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
+          description: Name of the catalog integration.
+        catalog:
+          $ref: '#/components/schemas/Catalog'
+          description: Type of catalog and its parameters.
+        table_format:
+          type: string
+          enum:
+          - ICEBERG
+          description: Table format of the catalog.
+        enabled:
+          type: boolean
+          description: 'whether this catalog integration is available to use for Iceberg
+            tables. '
+        comment:
+          type: string
+          description: Comment.
+        type:
+          type: string
+          readOnly: true
+          description: Type of the integration. Always CATALOG.
+        category:
+          type: string
+          readOnly: true
+          description: Category of the integration. Always CATALOG.
+        created_on:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Date and time when the catalog integration was created.
+      required:
+      - name
+      - catalog
+      - table_format
+      - enabled
+    Catalog:
+      type: object
+      properties:
+        catalog_source:
+          type: string
+          enum:
+          - GLUE
+          - OBJECT_STORE
+          - POLARIS
+          description: Type of external catalog
+      required:
+      - catalog_source
+      discriminator:
+        propertyName: catalog_source
+        mapping:
+          GLUE: Glue
+          OBJECT_STORE: ObjectStore
+          POLARIS: Polaris
+    Glue:
+      type: object
+      allOf:
+      - $ref: '#/components/schemas/Catalog'
+      properties:
+        glue_aws_role_arn:
+          type: string
+          description: ARN for AWS role to assume
+        glue_catalog_id:
+          type: string
+          description: Glue catalog id
+        glue_region:
+          type: string
+          description: AWS region of the Glue catalog. Must be specified if the Snowflake
+            account is not hosted on AWS.
+        catalog_namespace:
+          type: string
+          description: default AWS Glue catalog namespace for all Iceberg table that
+            use this catalog integration
+      required:
+      - glue_aws_role_arn
+      - glue_catalog_id
+      - catalog_namespace
+    ObjectStore:
+      type: object
+      allOf:
+      - $ref: '#/components/schemas/Catalog'
+    Polaris:
+      type: object
+      allOf:
+      - $ref: '#/components/schemas/Catalog'
+      properties:
+        catalog_namespace:
+          type: string
+          description: Default Polaris namespace used by all Iceberg tables associated
+            with this catalog integration
+        rest_config:
+          $ref: '#/components/schemas/RestConfig'
+          description: Information about the Polaris catalog account and catalog name.
+        rest_authentication:
+          $ref: '#/components/schemas/RestAuthentication'
+          description: Authentication details that Snowflake uses to connect to the
+            Polaris catalog.
+      required:
+      - catalog_namespace
+      - rest_config
+      - rest_authentication
+    RestConfig:
+      type: object
+      properties:
+        catalog_uri:
+          type: string
+          description: Customer's Polaris account locator URL
+        warehouse:
+          type: string
+          description: Name of the catalog to use in Polaris
+      required:
+      - catalog_uri
+      - warehouse
+    RestAuthentication:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+          - OAUTH
+          description: Authentication type.
+      required:
+      - type
+      discriminator:
+        propertyName: type
+        mapping:
+          OAUTH: OAuth
+    OAuth:
+      type: object
+      allOf:
+      - $ref: '#/components/schemas/RestAuthentication'
+      properties:
+        oauth_client_id:
+          type: string
+          description: The client ID of the OAuth2 credential associated with the
+            Polaris service connection.
+        oauth_client_secret:
+          type: string
+          description: The secret for the OAuth2 credential associated with the Polaris
+            service connection.
+        oauth_allowed_scopes:
+          type: array
+          items:
+            type: string
+          description: The scope of the OAuth token. Only one scope is included in
+            the Iceberg REST API specification, but catalogs can support more than
+            one scope in their implementation.
+      required:
+      - oauth_client_id
+      - oauth_client_secret
+      - oauth_allowed_scopes