From 44233fa5307cad4a10dfb33b67bae31da48c6798 Mon Sep 17 00:00:00 2001
From: Eduard Tudenhoefner <etudenhoefner@gmail.com>
Date: Fri, 18 Oct 2024 19:24:13 +0200
Subject: [PATCH] OpenAPI: Standardize credentials in loadTable/loadView
 responses (#10722)

---
 open-api/rest-catalog-open-api.py   | 24 ++++++++++++++++++++++
 open-api/rest-catalog-open-api.yaml | 32 +++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index f316dd7056a9..a16bf32155d3 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -467,6 +467,14 @@ class AssertViewUUID(BaseModel):
     uuid: str
 
 
+class StorageCredential(BaseModel):
+    prefix: str = Field(
+        ...,
+        description='Indicates a storage location prefix where the credential is relevant. Clients should choose the most specific prefix (by selecting the longest prefix) if several credentials of the same type are available.',
+    )
+    config: Dict[str, str]
+
+
 class PlanStatus(BaseModel):
     __root__: Literal['completed', 'submitted', 'cancelled', 'failed'] = Field(
         ..., description='Status of a server-side planning operation'
@@ -1195,6 +1203,11 @@ class LoadTableResult(BaseModel):
      - `s3.session-token`: if present, this value should be used for as the session token
      - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification
 
+    ## Storage Credentials
+
+    Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.
+    Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
+
     """
 
     metadata_location: Optional[str] = Field(
@@ -1204,6 +1217,9 @@ class LoadTableResult(BaseModel):
     )
     metadata: TableMetadata
     config: Optional[Dict[str, str]] = None
+    storage_credentials: Optional[List[StorageCredential]] = Field(
+        None, alias='storage-credentials'
+    )
 
 
 class ScanTasks(BaseModel):
@@ -1311,11 +1327,19 @@ class LoadViewResult(BaseModel):
 
     - `token`: Authorization bearer token to use for view requests if OAuth2 security is enabled
 
+    ## Storage Credentials
+
+    Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.
+    Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
+
     """
 
     metadata_location: str = Field(..., alias='metadata-location')
     metadata: ViewMetadata
     config: Optional[Dict[str, str]] = None
+    storage_credentials: Optional[List[StorageCredential]] = Field(
+        None, alias='storage-credentials'
+    )
 
 
 class ReportMetricsRequest(BaseModel):
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index c9fda66f155f..212a17c1295a 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -3103,6 +3103,21 @@ components:
         uuid:
           type: string
 
+    StorageCredential:
+      type: object
+      required:
+        - prefix
+        - config
+      properties:
+        prefix:
+          type: string
+          description: Indicates a storage location prefix where the credential is relevant. Clients should choose the most
+            specific prefix (by selecting the longest prefix) if several credentials of the same type are available.
+        config:
+          type: object
+          additionalProperties:
+            type: string
+
     LoadTableResult:
       description: |
         Result used when a table is successfully loaded.
@@ -3129,6 +3144,11 @@ components:
          - `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.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification
+
+        ## Storage Credentials
+
+        Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.
+        Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
       type: object
       required:
         - metadata
@@ -3142,6 +3162,10 @@ components:
           type: object
           additionalProperties:
             type: string
+        storage-credentials:
+          type: array
+          items:
+            $ref: '#/components/schemas/StorageCredential'
 
     ScanTasks:
       type: object
@@ -3395,6 +3419,10 @@ components:
 
         - `token`: Authorization bearer token to use for view requests if OAuth2 security is enabled
 
+        ## Storage Credentials
+
+        Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.
+        Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
       type: object
       required:
         - metadata-location
@@ -3408,6 +3436,10 @@ components:
           type: object
           additionalProperties:
             type: string
+        storage-credentials:
+          type: array
+          items:
+            $ref: '#/components/schemas/StorageCredential'
 
     TokenType:
       type: string