From 231b4dddeeda9c20710754b1d8179fa5cbfaacad Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Fri, 2 Feb 2024 10:14:52 -0800
Subject: [PATCH 01/14] Add pagination to open api spec for listing of
 namespaces, tables, views

---
 open-api/rest-catalog-open-api.py   |  2 +
 open-api/rest-catalog-open-api.yaml | 96 +++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index 719e77b0ad33..a0f119bdd405 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -581,10 +581,12 @@ class GetNamespaceResponse(BaseModel):
 
 
 class ListTablesResponse(BaseModel):
+    next_page_token: Optional[str] = Field(None, alias='next-page-token')
     identifiers: Optional[List[TableIdentifier]] = Field(None, unique_items=True)
 
 
 class ListNamespacesResponse(BaseModel):
+    next_page_token: Optional[str] = Field(None, alias='next-page-token')
     namespaces: Optional[List[Namespace]] = Field(None, unique_items=True)
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index b21527946216..37ef9a96c580 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -212,6 +212,34 @@ paths:
           schema:
             type: string
           example: "accounting%1Ftax"
+        - name: pageToken
+          in: query
+          description:
+            Allows clients to make use of pagination by signaling to the service that they would
+            prefer requests to be paginated to a “reasonable” number of results.
+            
+            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
+            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
+            and honor the contracts specified above by returning a non-empty continuation token
+            if there are more results available, or an empty token or missing field indicating no more results.
+            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
+            
+            Old clients should not be specifying the new parameters
+            For servers that support pagination, they would notice the lack of “continuationToken”
+            in the query string and return all results at once (mimicking existing behavior).
+            For servers not supporting pagination, this is the current state and they would return all values at once.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
+        - name: pageSize
+          in: query
+          description:
+            An upper bound on the number of results to return on the next page.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
       responses:
         200:
           $ref: '#/components/responses/ListNamespacesResponse'
@@ -448,6 +476,35 @@ paths:
       summary: List all table identifiers underneath a given namespace
       description: Return all table identifiers under this namespace
       operationId: listTables
+      parameters:
+        - name: pageToken
+          in: query
+          description:
+            Allows clients to make use of pagination by signaling to the service that they would
+            prefer requests to be paginated to a “reasonable” number of results.
+  
+            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
+            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
+            and honor the contracts specified above by returning a non-empty continuation token
+            if there are more results available, or an empty token or missing field indicating no more results.
+            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
+  
+            Old clients should not be specifying the new parameters
+            For servers that support pagination, they would notice the lack of “continuationToken”
+            in the query string and return all results at once (mimicking existing behavior).
+            For servers not supporting pagination, this is the current state and they would return all values at once.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
+        - name: pageSize
+          in: query
+          description:
+            An upper bound on the number of results to return on the next page.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
       responses:
         200:
           $ref: '#/components/responses/ListTablesResponse'
@@ -1070,6 +1127,35 @@ paths:
       summary: List all view identifiers underneath a given namespace
       description: Return all view identifiers under this namespace
       operationId: listViews
+      parameters:
+        - name: pageToken
+          in: query
+          description:
+            Allows clients to make use of pagination by signaling to the service that they would
+            prefer requests to be paginated to a “reasonable” number of results.
+            
+            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
+            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
+            and honor the contracts specified above by returning a non-empty continuation token
+            if there are more results available, or an empty token or missing field indicating no more results.
+            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
+            
+            Old clients should not be specifying the new parameters
+            For servers that support pagination, they would notice the lack of “continuationToken”
+            in the query string and return all results at once (mimicking existing behavior).
+            For servers not supporting pagination, this is the current state and they would return all values at once.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
+        - name: pageSize
+          in: query
+          description:
+            An upper bound on the number of results to return on the next page.
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string
       responses:
         200:
           $ref: '#/components/responses/ListTablesResponse'
@@ -3169,6 +3255,11 @@ components:
     ListTablesResponse:
       type: object
       properties:
+        next-page-token:
+          description:
+            A non-empty next page token indicates more results. An absent or emptyPageToken indicates the returned results are complete.
+            This should be used in the next request for the query parameter “pageToken"
+          type: string
         identifiers:
           type: array
           uniqueItems: true
@@ -3178,6 +3269,11 @@ components:
     ListNamespacesResponse:
       type: object
       properties:
+        next-page-token:
+          description:
+            A non-empty next page token indicates more results. An absent or emptyPageToken indicates the returned results are complete.
+            This should be used in the next request for the query parameter “pageToken"
+          type: string
         namespaces:
           type: array
           uniqueItems: true

From a3dc72004373852c71be0ccef5bcf04a88a873f8 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Wed, 7 Feb 2024 15:09:56 -0800
Subject: [PATCH 02/14] Rev for pagination in open api spec

---
 open-api/rest-catalog-open-api.yaml | 132 ++++++++++------------------
 1 file changed, 44 insertions(+), 88 deletions(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 37ef9a96c580..f3a43d8ce8d0 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -201,6 +201,8 @@ paths:
         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:
@@ -212,34 +214,6 @@ paths:
           schema:
             type: string
           example: "accounting%1Ftax"
-        - name: pageToken
-          in: query
-          description:
-            Allows clients to make use of pagination by signaling to the service that they would
-            prefer requests to be paginated to a “reasonable” number of results.
-            
-            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
-            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
-            and honor the contracts specified above by returning a non-empty continuation token
-            if there are more results available, or an empty token or missing field indicating no more results.
-            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
-            
-            Old clients should not be specifying the new parameters
-            For servers that support pagination, they would notice the lack of “continuationToken”
-            in the query string and return all results at once (mimicking existing behavior).
-            For servers not supporting pagination, this is the current state and they would return all values at once.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
-        - name: pageSize
-          in: query
-          description:
-            An upper bound on the number of results to return on the next page.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
       responses:
         200:
           $ref: '#/components/responses/ListNamespacesResponse'
@@ -477,34 +451,8 @@ paths:
       description: Return all table identifiers under this namespace
       operationId: listTables
       parameters:
-        - name: pageToken
-          in: query
-          description:
-            Allows clients to make use of pagination by signaling to the service that they would
-            prefer requests to be paginated to a “reasonable” number of results.
-  
-            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
-            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
-            and honor the contracts specified above by returning a non-empty continuation token
-            if there are more results available, or an empty token or missing field indicating no more results.
-            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
-  
-            Old clients should not be specifying the new parameters
-            For servers that support pagination, they would notice the lack of “continuationToken”
-            in the query string and return all results at once (mimicking existing behavior).
-            For servers not supporting pagination, this is the current state and they would return all values at once.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
-        - name: pageSize
-          in: query
-          description:
-            An upper bound on the number of results to return on the next page.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/page-token'
+        - $ref: '#/components/parameters/page-size'
       responses:
         200:
           $ref: '#/components/responses/ListTablesResponse'
@@ -1128,34 +1076,8 @@ paths:
       description: Return all view identifiers under this namespace
       operationId: listViews
       parameters:
-        - name: pageToken
-          in: query
-          description:
-            Allows clients to make use of pagination by signaling to the service that they would
-            prefer requests to be paginated to a “reasonable” number of results.
-            
-            New Clients always start the request by sending a required empty “pageToken” e.g. GET /tables?continuationToken=””
-            Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
-            and honor the contracts specified above by returning a non-empty continuation token
-            if there are more results available, or an empty token or missing field indicating no more results.
-            Servers that are non-pagination aware will ignore the token and return all results as they previously did.
-            
-            Old clients should not be specifying the new parameters
-            For servers that support pagination, they would notice the lack of “continuationToken”
-            in the query string and return all results at once (mimicking existing behavior).
-            For servers not supporting pagination, this is the current state and they would return all values at once.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
-        - name: pageSize
-          in: query
-          description:
-            An upper bound on the number of results to return on the next page.
-          required: false
-          allowEmptyValue: true
-          schema:
-            type: string
+        - $ref: '#/components/parameters/page-token'
+        - $ref: '#/components/parameters/page-size'
       responses:
         200:
           $ref: '#/components/responses/ListTablesResponse'
@@ -1568,6 +1490,38 @@ components:
       explode: false
       example: "vended-credentials,remote-signing"
 
+    page-token:
+      name: pageToken
+      in: query
+      description:
+        A unique token which allows clients to make use of pagination by signaling to the service that they would
+        prefer requests to be paginated based on the number of items specified by pageSize.
+        
+        New Clients always start the request by sending a required empty pageToken e.g. GET /tables?pageToken
+        Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
+        and honor the contracts specified above by returning a non-empty next pageToken 
+        if there are more results available, or an empty next pageToken indicating no more results.
+        Servers that are non-pagination aware will ignore the token and return all results as they previously did.
+        
+        Old clients should not be specifying the new parameters
+        For servers that support pagination, they would notice the lack of the pageToken
+        in the query string and return all results at once (mimicking existing behavior).
+        For servers not supporting pagination, this is the current state and they would return all values at once.
+      required: false
+      allowEmptyValue: true
+      schema:
+        type: string
+
+    page-size:
+      name: pageSize
+      in: query
+      description:
+        An upper bound on the number of results to return on the next page.
+      required: false
+      allowEmptyValue: true
+      schema:
+        type: string
+
   ##############################
   # Application Schema Objects #
   ##############################
@@ -3257,8 +3211,9 @@ components:
       properties:
         next-page-token:
           description:
-            A non-empty next page token indicates more results. An absent or emptyPageToken indicates the returned results are complete.
-            This should be used in the next request for the query parameter “pageToken"
+            A unique next page token, when non-empty this indicates that more results can be returned by server,
+            and when empty this indicates the returned results are complete.
+            This should be used in the next request for the query parameter of pageToken.
           type: string
         identifiers:
           type: array
@@ -3271,8 +3226,9 @@ components:
       properties:
         next-page-token:
           description:
-            A non-empty next page token indicates more results. An absent or emptyPageToken indicates the returned results are complete.
-            This should be used in the next request for the query parameter “pageToken"
+            A unique next page token, when non-empty this indicates that more results can be returned by server, 
+            and when empty this indicates the returned results are complete.
+            This should be used in the next request for the query parameter of pageToken.
           type: string
         namespaces:
           type: array

From a1e20ad31700709049ef237a7fafe2ba2413f75c Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Sun, 11 Feb 2024 16:06:43 -0800
Subject: [PATCH 03/14] Fix writing in pagination descriptions

---
 open-api/rest-catalog-open-api.py   | 21 ++++++++++++-------
 open-api/rest-catalog-open-api.yaml | 31 ++++++++++++-----------------
 2 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index a0f119bdd405..e9542b8c4c84 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -75,6 +75,13 @@ class Namespace(BaseModel):
     )
 
 
+class NextPageToken(BaseModel):
+    __root__: str = Field(
+        ...,
+        description='An opaque next page token, when non-empty this indicates that more results can be returned by server, and when empty this indicates the returned results are complete. This should be used in the next request for the query parameter of pageToken.',
+    )
+
+
 class TableIdentifier(BaseModel):
     namespace: Namespace
     name: str
@@ -581,12 +588,12 @@ class GetNamespaceResponse(BaseModel):
 
 
 class ListTablesResponse(BaseModel):
-    next_page_token: Optional[str] = Field(None, alias='next-page-token')
+    next_page_token: Optional[NextPageToken] = Field(None, alias='next-page-token')
     identifiers: Optional[List[TableIdentifier]] = Field(None, unique_items=True)
 
 
 class ListNamespacesResponse(BaseModel):
-    next_page_token: Optional[str] = Field(None, alias='next-page-token')
+    next_page_token: Optional[NextPageToken] = Field(None, alias='next-page-token')
     namespaces: Optional[List[Namespace]] = Field(None, unique_items=True)
 
 
@@ -631,7 +638,7 @@ class TransformTerm(BaseModel):
     term: Reference
 
 
-class ReportMetricsRequest2(CommitReport):
+class ReportMetricsRequest1(CommitReport):
     report_type: str = Field(..., alias='report-type')
 
 
@@ -909,8 +916,8 @@ class LoadViewResult(BaseModel):
     config: Optional[Dict[str, str]] = None
 
 
-class ReportMetricsRequest(BaseModel):
-    __root__: Union[ReportMetricsRequest1, ReportMetricsRequest2]
+class ReportMetricsRequest2(BaseModel):
+    __root__: Union[ReportMetricsRequest, ReportMetricsRequest1]
 
 
 class ScanReport(BaseModel):
@@ -936,7 +943,7 @@ class Schema(StructType):
     )
 
 
-class ReportMetricsRequest1(ScanReport):
+class ReportMetricsRequest(ScanReport):
     report_type: str = Field(..., alias='report-type')
 
 
@@ -949,4 +956,4 @@ class ReportMetricsRequest1(ScanReport):
 AddSchemaUpdate.update_forward_refs()
 CreateTableRequest.update_forward_refs()
 CreateViewRequest.update_forward_refs()
-ReportMetricsRequest.update_forward_refs()
+ReportMetricsRequest2.update_forward_refs()
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index f3a43d8ce8d0..e10e07a29436 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1497,16 +1497,11 @@ components:
         A unique token which allows clients to make use of pagination by signaling to the service that they would
         prefer requests to be paginated based on the number of items specified by pageSize.
         
-        New Clients always start the request by sending a required empty pageToken e.g. GET /tables?pageToken
+        Clients that support pagination initiate the request by sending an empty pageToken e.g. GET /tables?pageToken
         Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
         and honor the contracts specified above by returning a non-empty next pageToken 
         if there are more results available, or an empty next pageToken indicating no more results.
-        Servers that are non-pagination aware will ignore the token and return all results as they previously did.
-        
-        Old clients should not be specifying the new parameters
-        For servers that support pagination, they would notice the lack of the pageToken
-        in the query string and return all results at once (mimicking existing behavior).
-        For servers not supporting pagination, this is the current state and they would return all values at once.
+        Servers that are non-pagination aware will ignore the token and return all results.
       required: false
       allowEmptyValue: true
       schema:
@@ -1516,7 +1511,8 @@ components:
       name: pageSize
       in: query
       description:
-        An upper bound on the number of results to return on the next page.
+        The number of results to return on the next page for servers that support pagination.
+        For servers that do not support pagination clients may receive results larger than the indicated pageSize.
       required: false
       allowEmptyValue: true
       schema:
@@ -1621,6 +1617,13 @@ components:
         type: string
       example: [ "accounting", "tax" ]
 
+    NextPageToken:
+      description:
+        An opaque next page token, when non-empty this indicates that more results can be returned by server,
+        and when empty this indicates the returned results are complete.
+        This should be used in the next request for the query parameter of pageToken.
+      type: string
+
     TableIdentifier:
       type: object
       required:
@@ -3210,11 +3213,7 @@ components:
       type: object
       properties:
         next-page-token:
-          description:
-            A unique next page token, when non-empty this indicates that more results can be returned by server,
-            and when empty this indicates the returned results are complete.
-            This should be used in the next request for the query parameter of pageToken.
-          type: string
+          $ref: '#/components/schemas/NextPageToken'
         identifiers:
           type: array
           uniqueItems: true
@@ -3225,11 +3224,7 @@ components:
       type: object
       properties:
         next-page-token:
-          description:
-            A unique next page token, when non-empty this indicates that more results can be returned by server, 
-            and when empty this indicates the returned results are complete.
-            This should be used in the next request for the query parameter of pageToken.
-          type: string
+          $ref: '#/components/schemas/NextPageToken'
         namespaces:
           type: array
           uniqueItems: true

From 4128211b37770ba3c04c11eabe9dcac14a7296bb Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Sun, 11 Feb 2024 16:09:48 -0800
Subject: [PATCH 04/14] Use opaque token

---
 open-api/rest-catalog-open-api.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index e10e07a29436..6e29baf3836a 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1494,7 +1494,7 @@ components:
       name: pageToken
       in: query
       description:
-        A unique token which allows clients to make use of pagination by signaling to the service that they would
+        An opaque token which allows clients to make use of pagination by signaling to the service that they would
         prefer requests to be paginated based on the number of items specified by pageSize.
         
         Clients that support pagination initiate the request by sending an empty pageToken e.g. GET /tables?pageToken

From 25656b2829d3cc82fc1203fb2cc806d24f88f74b Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Tue, 13 Feb 2024 11:30:55 -0800
Subject: [PATCH 05/14] Rev on pagination pr writing

---
 open-api/rest-catalog-open-api.yaml | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 6e29baf3836a..dc35055f9355 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1494,13 +1494,12 @@ components:
       name: pageToken
       in: query
       description:
-        An opaque token which allows clients to make use of pagination by signaling to the service that they would
-        prefer requests to be paginated based on the number of items specified by pageSize.
+        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service that they would
+        that they would prefer response to be paginated. If pageSize is specified, the service should return exactly the number of items specified by it.
         
         Clients that support pagination initiate the request by sending an empty pageToken e.g. GET /tables?pageToken
         Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
-        and honor the contracts specified above by returning a non-empty next pageToken 
-        if there are more results available, or an empty next pageToken indicating no more results.
+        and honor the contracts specified above by returning a NextPageToken in response if there are more results available.
         Servers that are non-pagination aware will ignore the token and return all results.
       required: false
       allowEmptyValue: true
@@ -1619,8 +1618,7 @@ components:
 
     NextPageToken:
       description:
-        An opaque next page token, when non-empty this indicates that more results can be returned by server,
-        and when empty this indicates the returned results are complete.
+        An opaque next page token, when non-empty this indicates that more results can be returned by server.
         This should be used in the next request for the query parameter of pageToken.
       type: string
 

From e0307a1f54b0d537834d38cf0be971fa68a09a36 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Tue, 13 Feb 2024 11:35:19 -0800
Subject: [PATCH 06/14] Rev on pagination pr writing py file

---
 open-api/rest-catalog-open-api.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index e9542b8c4c84..3d347ac32b61 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -78,7 +78,7 @@ class Namespace(BaseModel):
 class NextPageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque next page token, when non-empty this indicates that more results can be returned by server, and when empty this indicates the returned results are complete. This should be used in the next request for the query parameter of pageToken.',
+        description='An opaque next page token, when non-empty this indicates that more results can be returned by server. This should be used in the next request for the query parameter of pageToken.',
     )
 
 
@@ -638,7 +638,7 @@ class TransformTerm(BaseModel):
     term: Reference
 
 
-class ReportMetricsRequest1(CommitReport):
+class ReportMetricsRequest2(CommitReport):
     report_type: str = Field(..., alias='report-type')
 
 
@@ -916,8 +916,8 @@ class LoadViewResult(BaseModel):
     config: Optional[Dict[str, str]] = None
 
 
-class ReportMetricsRequest2(BaseModel):
-    __root__: Union[ReportMetricsRequest, ReportMetricsRequest1]
+class ReportMetricsRequest(BaseModel):
+    __root__: Union[ReportMetricsRequest1, ReportMetricsRequest2]
 
 
 class ScanReport(BaseModel):
@@ -943,7 +943,7 @@ class Schema(StructType):
     )
 
 
-class ReportMetricsRequest(ScanReport):
+class ReportMetricsRequest1(ScanReport):
     report_type: str = Field(..., alias='report-type')
 
 
@@ -956,4 +956,4 @@ class ReportMetricsRequest(ScanReport):
 AddSchemaUpdate.update_forward_refs()
 CreateTableRequest.update_forward_refs()
 CreateViewRequest.update_forward_refs()
-ReportMetricsRequest2.update_forward_refs()
+ReportMetricsRequest.update_forward_refs()

From c78f2518a5a1341db79417b37abc498783bbf00b Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Tue, 13 Feb 2024 14:48:01 -0800
Subject: [PATCH 07/14] Rev on description for pageSize

---
 open-api/rest-catalog-open-api.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index dc35055f9355..56cc27980c4e 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1510,8 +1510,8 @@ components:
       name: pageSize
       in: query
       description:
-        The number of results to return on the next page for servers that support pagination.
-        For servers that do not support pagination clients may receive results larger than the indicated pageSize.
+        For servers that support pagination, this signals an upper bound of the number of results that client will receive. 
+        For servers that do not support pagination, clients may receive results larger than the indicated pageSize.
       required: false
       allowEmptyValue: true
       schema:

From e25c70a6d87a5b697e28bcaecbdf059bb67ffdd3 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Wed, 14 Feb 2024 13:51:56 -0800
Subject: [PATCH 08/14] revise pageToken description

---
 open-api/rest-catalog-open-api.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 56cc27980c4e..0dcfac85c6cd 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1494,13 +1494,13 @@ components:
       name: pageToken
       in: query
       description:
-        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service that they would
-        that they would prefer response to be paginated. If pageSize is specified, the service should return exactly the number of items specified by it.
+        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service
+        that they would prefer response to be paginated.
         
-        Clients that support pagination initiate the request by sending an empty pageToken e.g. GET /tables?pageToken
-        Servers supporting pagination would recognize pagination is requested due to the presence of the pageToken
-        and honor the contracts specified above by returning a NextPageToken in response if there are more results available.
-        Servers that are non-pagination aware will ignore the token and return all results.
+        Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
+        For servers that support pagination, they would recognize pageToken and honor the contracts specified above 
+        by returning a NextPageToken in response if there are more results available.
+        For servers that do not support pagination, they will ignore the token and return all results.
       required: false
       allowEmptyValue: true
       schema:

From 696532599b33dd3e88d2876e6fff2db98b5d0885 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Thu, 15 Feb 2024 10:33:30 -0800
Subject: [PATCH 09/14] minor rev and make int for pageSize

---
 open-api/rest-catalog-open-api.py   | 2 +-
 open-api/rest-catalog-open-api.yaml | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index 3d347ac32b61..8f882308d786 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -78,7 +78,7 @@ class Namespace(BaseModel):
 class NextPageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque next page token, when non-empty this indicates that more results can be returned by server. This should be used in the next request for the query parameter of pageToken.',
+        description='An opaque next page token, when non-null and non-empty this indicates that more results can be returned by server. This should be used in the next request for the query parameter of pageToken.',
     )
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 0dcfac85c6cd..91d14b6b2a9a 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1498,7 +1498,7 @@ components:
         that they would prefer response to be paginated.
         
         Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
-        For servers that support pagination, they would recognize pageToken and honor the contracts specified above 
+        For servers that support pagination, they will recognize pageToken and honor the contracts specified above 
         by returning a NextPageToken in response if there are more results available.
         For servers that do not support pagination, they will ignore the token and return all results.
       required: false
@@ -1515,7 +1515,7 @@ components:
       required: false
       allowEmptyValue: true
       schema:
-        type: string
+        type: integer
 
   ##############################
   # Application Schema Objects #
@@ -1618,7 +1618,7 @@ components:
 
     NextPageToken:
       description:
-        An opaque next page token, when non-empty this indicates that more results can be returned by server.
+        An opaque next page token, when non-null and non-empty this indicates that more results can be returned by server.
         This should be used in the next request for the query parameter of pageToken.
       type: string
 

From 77df1a5d67086b6d422c833767a69de6b3c290b3 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Fri, 16 Feb 2024 09:46:32 -0800
Subject: [PATCH 10/14] minor rev and remove emtpy val true for pageSize

---
 open-api/rest-catalog-open-api.yaml | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 91d14b6b2a9a..367f92e9bfd7 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1495,12 +1495,12 @@ components:
       in: query
       description:
         An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service
-        that they would prefer response to be paginated.
+        that they would prefer the response to be paginated.
         
         Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
-        For servers that support pagination, they will recognize pageToken and honor the contracts specified above 
-        by returning a NextPageToken in response if there are more results available.
-        For servers that do not support pagination, they will ignore the token and return all results.
+        For servers that support pagination, they will recognize pageToken and return a NextPageToken in response if there are more results available.
+        After initial request, it is expected that the NextPageToken from the last response be used as the pageToken in the subsequent request.
+        For servers that do not support pagination, they will ignore the pageToken and return all results.
       required: false
       allowEmptyValue: true
       schema:
@@ -1513,7 +1513,6 @@ components:
         For servers that support pagination, this signals an upper bound of the number of results that client will receive. 
         For servers that do not support pagination, clients may receive results larger than the indicated pageSize.
       required: false
-      allowEmptyValue: true
       schema:
         type: integer
 

From aab3caab0b70c4064a0a09b059758c586dcabf1a Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Mon, 19 Feb 2024 11:32:27 -0800
Subject: [PATCH 11/14] use only PageToken instead of NextPageToken

---
 open-api/rest-catalog-open-api.py   |  8 ++++----
 open-api/rest-catalog-open-api.yaml | 25 +++++++++++--------------
 2 files changed, 15 insertions(+), 18 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index 8f882308d786..84551f0d5500 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -75,10 +75,10 @@ class Namespace(BaseModel):
     )
 
 
-class NextPageToken(BaseModel):
+class PageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque next page token, when non-null and non-empty this indicates that more results can be returned by server. This should be used in the next request for the query parameter of pageToken.',
+        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service that they would prefer the response to be paginated.\nClients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken= For servers that support pagination, they will recognize pageToken and return a next pageToken in response if there are more results available. After initial request, it is expected that the next pageToken from the last response be used in the subsequent request. For servers that do not support pagination, they will ignore the pageToken and return all results.',
     )
 
 
@@ -588,12 +588,12 @@ class GetNamespaceResponse(BaseModel):
 
 
 class ListTablesResponse(BaseModel):
-    next_page_token: Optional[NextPageToken] = Field(None, alias='next-page-token')
+    next_page_token: Optional[PageToken] = Field(None, alias='next-page-token')
     identifiers: Optional[List[TableIdentifier]] = Field(None, unique_items=True)
 
 
 class ListNamespacesResponse(BaseModel):
-    next_page_token: Optional[NextPageToken] = Field(None, alias='next-page-token')
+    next_page_token: Optional[PageToken] = Field(None, alias='next-page-token')
     namespaces: Optional[List[Namespace]] = Field(None, unique_items=True)
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 367f92e9bfd7..6de36c48c803 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1493,18 +1493,10 @@ components:
     page-token:
       name: pageToken
       in: query
-      description:
-        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service
-        that they would prefer the response to be paginated.
-        
-        Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
-        For servers that support pagination, they will recognize pageToken and return a NextPageToken in response if there are more results available.
-        After initial request, it is expected that the NextPageToken from the last response be used as the pageToken in the subsequent request.
-        For servers that do not support pagination, they will ignore the pageToken and return all results.
       required: false
       allowEmptyValue: true
       schema:
-        type: string
+        $ref: '#/components/schemas/PageToken'
 
     page-size:
       name: pageSize
@@ -1615,10 +1607,15 @@ components:
         type: string
       example: [ "accounting", "tax" ]
 
-    NextPageToken:
+    PageToken:
       description:
-        An opaque next page token, when non-null and non-empty this indicates that more results can be returned by server.
-        This should be used in the next request for the query parameter of pageToken.
+        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service
+        that they would prefer the response to be paginated.
+
+        Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
+        For servers that support pagination, they will recognize pageToken and return a next pageToken in response if there are more results available.
+        After initial request, it is expected that the next pageToken from the last response be used in the subsequent request.
+        For servers that do not support pagination, they will ignore the pageToken and return all results.
       type: string
 
     TableIdentifier:
@@ -3210,7 +3207,7 @@ components:
       type: object
       properties:
         next-page-token:
-          $ref: '#/components/schemas/NextPageToken'
+          $ref: '#/components/schemas/PageToken'
         identifiers:
           type: array
           uniqueItems: true
@@ -3221,7 +3218,7 @@ components:
       type: object
       properties:
         next-page-token:
-          $ref: '#/components/schemas/NextPageToken'
+          $ref: '#/components/schemas/PageToken'
         namespaces:
           type: array
           uniqueItems: true

From eed29cc6f8cbc1a518c3fa738e9321f9407cefb6 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Wed, 21 Feb 2024 10:10:03 -0800
Subject: [PATCH 12/14] address jack and nastra comments

---
 open-api/rest-catalog-open-api.py   |  2 +-
 open-api/rest-catalog-open-api.yaml | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index 84551f0d5500..c2fd881cf642 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -78,7 +78,7 @@ class Namespace(BaseModel):
 class PageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service that they would prefer the response to be paginated.\nClients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken= For servers that support pagination, they will recognize pageToken and return a next pageToken in response if there are more results available. After initial request, it is expected that the next pageToken from the last response be used in the subsequent request. For servers that do not support pagination, they will ignore the pageToken and return all results.',
+        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). Clients will initiate the first paginated request by sending an empty pageToken e.g. GET /tables?pageToken or GET /tables?pageToken= signaling to the service that the response should be paginated.\nFor servers that support pagination, they will recognize `pageToken` and return a next-page-token in response if there are more results available. After the initial request, it is expected that the next-page-token from the last response, is used in the subsequent request. For servers that do not support pagination, they will ignore the `pageToken` and return all results.',
     )
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 6de36c48c803..83d7fe3d44f1 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1502,8 +1502,8 @@ components:
       name: pageSize
       in: query
       description:
-        For servers that support pagination, this signals an upper bound of the number of results that client will receive. 
-        For servers that do not support pagination, clients may receive results larger than the indicated pageSize.
+        For servers that support pagination, this signals an upper bound of the number of results that a client will receive. 
+        For servers that do not support pagination, clients may receive results larger than the indicated `pageSize`.
       required: false
       schema:
         type: integer
@@ -1609,13 +1609,13 @@ components:
 
     PageToken:
       description:
-        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables) by signaling to the service
-        that they would prefer the response to be paginated.
+        An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). 
+        Clients will initiate the first paginated request by sending an empty pageToken e.g. GET /tables?pageToken or GET /tables?pageToken=
+        signaling to the service that the response should be paginated.
 
-        Clients will initiate the request by sending an empty pageToken e.g. GET /tables?pageToken or /tables?pageToken=
-        For servers that support pagination, they will recognize pageToken and return a next pageToken in response if there are more results available.
-        After initial request, it is expected that the next pageToken from the last response be used in the subsequent request.
-        For servers that do not support pagination, they will ignore the pageToken and return all results.
+        For servers that support pagination, they will recognize `pageToken` and return a next-page-token in response if there are more results available.
+        After the initial request, it is expected that the next-page-token from the last response, is used in the subsequent request.
+        For servers that do not support pagination, they will ignore the `pageToken` and return all results.
       type: string
 
     TableIdentifier:

From 918a1ade23e9b427b97b3f99eb02956405e70be0 Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Wed, 21 Feb 2024 10:21:51 -0800
Subject: [PATCH 13/14] address final comments

---
 open-api/rest-catalog-open-api.py   | 2 +-
 open-api/rest-catalog-open-api.yaml | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index c2fd881cf642..fb01f1b1f5f1 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -78,7 +78,7 @@ class Namespace(BaseModel):
 class PageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). Clients will initiate the first paginated request by sending an empty pageToken e.g. GET /tables?pageToken or GET /tables?pageToken= signaling to the service that the response should be paginated.\nFor servers that support pagination, they will recognize `pageToken` and return a next-page-token in response if there are more results available. After the initial request, it is expected that the next-page-token from the last response, is used in the subsequent request. For servers that do not support pagination, they will ignore the `pageToken` and return all results.',
+        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=` signaling to the service that the response should be paginated.\nFor servers that support pagination, they will recognize `pageToken` and return a `next-page-token` in response if there are more results available. After the initial request, it is expected that the `next-page-token` from the last response is used in the subsequent request. For servers that do not support pagination, they will ignore the `pageToken` and return all results.',
     )
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index 83d7fe3d44f1..d831740d34df 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1610,11 +1610,11 @@ components:
     PageToken:
       description:
         An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). 
-        Clients will initiate the first paginated request by sending an empty pageToken e.g. GET /tables?pageToken or GET /tables?pageToken=
+        Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`
         signaling to the service that the response should be paginated.
 
-        For servers that support pagination, they will recognize `pageToken` and return a next-page-token in response if there are more results available.
-        After the initial request, it is expected that the next-page-token from the last response, is used in the subsequent request.
+        For servers that support pagination, they will recognize `pageToken` and return a `next-page-token` in response if there are more results available.
+        After the initial request, it is expected that the `next-page-token` from the last response is used in the subsequent request.
         For servers that do not support pagination, they will ignore the `pageToken` and return all results.
       type: string
 

From ef4af36628e1f0963f762c4a3f56ea8c082f57ba Mon Sep 17 00:00:00 2001
From: Rahil Chertara <rchertar@amazon.com>
Date: Sun, 25 Feb 2024 14:03:17 -0800
Subject: [PATCH 14/14] remove they and use min 1 for pageSize

---
 open-api/rest-catalog-open-api.py   | 2 +-
 open-api/rest-catalog-open-api.yaml | 7 ++++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py
index fb01f1b1f5f1..ad1df97ab799 100644
--- a/open-api/rest-catalog-open-api.py
+++ b/open-api/rest-catalog-open-api.py
@@ -78,7 +78,7 @@ class Namespace(BaseModel):
 class PageToken(BaseModel):
     __root__: str = Field(
         ...,
-        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=` signaling to the service that the response should be paginated.\nFor servers that support pagination, they will recognize `pageToken` and return a `next-page-token` in response if there are more results available. After the initial request, it is expected that the `next-page-token` from the last response is used in the subsequent request. For servers that do not support pagination, they will ignore the `pageToken` and return all results.',
+        description='An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables). Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=` signaling to the service that the response should be paginated.\nServers that support pagination will recognize `pageToken` and return a `next-page-token` in response if there are more results available. After the initial request, it is expected that the value of `next-page-token` from the last response is used in the subsequent request. Servers that do not support pagination will ignore `next-page-token` and return all results.',
     )
 
 
diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
index d831740d34df..fc98faba52c5 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -1507,6 +1507,7 @@ components:
       required: false
       schema:
         type: integer
+        minimum: 1
 
   ##############################
   # Application Schema Objects #
@@ -1613,9 +1614,9 @@ components:
         Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`
         signaling to the service that the response should be paginated.
 
-        For servers that support pagination, they will recognize `pageToken` and return a `next-page-token` in response if there are more results available.
-        After the initial request, it is expected that the `next-page-token` from the last response is used in the subsequent request.
-        For servers that do not support pagination, they will ignore the `pageToken` and return all results.
+        Servers that support pagination will recognize `pageToken` and return a `next-page-token` in response if there are more results available.
+        After the initial request, it is expected that the value of `next-page-token` from the last response is used in the subsequent request.
+        Servers that do not support pagination will ignore `next-page-token` and return all results.
       type: string
 
     TableIdentifier: