From 84f86cff627c5b7851a2c986ac7a724c41907499 Mon Sep 17 00:00:00 2001 From: Rahil Chertara Date: Sun, 10 Mar 2024 16:25:20 -0700 Subject: [PATCH 1/4] Fix pagination description based on new feedback --- open-api/rest-catalog-open-api.py | 2 +- open-api/rest-catalog-open-api.yaml | 26 ++++++++++++++++++++------ 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index 77dcad9cfba6..5f279abffa75 100644 --- a/open-api/rest-catalog-open-api.py +++ b/open-api/rest-catalog-open-api.py @@ -80,7 +80,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.\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.', + description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted or set to `null` in the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', ) diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml index 77aabc834adb..afc8f8a3a264 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -1610,13 +1610,27 @@ 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=` - signaling to the service that the response should be paginated. + An opaque token that allows clients to make use of pagination for list APIs + (e.g. ListTables). Clients may initiate the first paginated request by sending an empty + query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=` + + Servers that support pagination should identify the `pageToken` parameter and return a + `next-page-token` in the response if there are more results available. After the initial + request, the value of `next-page-token` from each response must be used as the `pageToken` + parameter value for the next request. The server must return `null` value for the + `next-page-token` in the last response. + + Servers that support pagination must return all results in a single response with the value + of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the + request. + + Servers that do not support pagination should ignore the `pageToken` parameter and return + all results in a single response. The `next-page-token` must be omitted or set to `null` + in the response. + + Clients must interpret either `null` or missing response value of `next-page-token` as + the end of the listing 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: From 116191525da595c74969d3231a8a303073f6fb60 Mon Sep 17 00:00:00 2001 From: Rahil Chertara Date: Sun, 10 Mar 2024 16:31:25 -0700 Subject: [PATCH 2/4] omit or null --- open-api/rest-catalog-open-api.py | 2 +- open-api/rest-catalog-open-api.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index 5f279abffa75..a905fdad8fd9 100644 --- a/open-api/rest-catalog-open-api.py +++ b/open-api/rest-catalog-open-api.py @@ -80,7 +80,7 @@ class Namespace(BaseModel): class PageToken(BaseModel): __root__: str = Field( ..., - description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted or set to `null` in the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', + description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must omit or return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted or set to `null` in the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', ) diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml index afc8f8a3a264..9e15c3b7eb5c 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -1617,7 +1617,7 @@ components: Servers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` - parameter value for the next request. The server must return `null` value for the + parameter value for the next request. The server must omit or return `null` value for the `next-page-token` in the last response. Servers that support pagination must return all results in a single response with the value From 7a1cdfd78ad36092f728f7c99f64bdce4bc063bb Mon Sep 17 00:00:00 2001 From: Rahil Chertara Date: Wed, 13 Mar 2024 15:27:12 -0700 Subject: [PATCH 3/4] address clarifying comments --- open-api/rest-catalog-open-api.py | 2 +- open-api/rest-catalog-open-api.yaml | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index a905fdad8fd9..ca3045bf7d0c 100644 --- a/open-api/rest-catalog-open-api.py +++ b/open-api/rest-catalog-open-api.py @@ -80,7 +80,7 @@ class Namespace(BaseModel): class PageToken(BaseModel): __root__: str = Field( ..., - description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must omit or return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted or set to `null` in the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', + description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server.\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted from the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', ) diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml index 9e15c3b7eb5c..eb6efec1cb37 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -1612,21 +1612,20 @@ components: description: An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty - query parameter `pageToken` to the server e.g. `GET /tables?pageToken` or `GET /tables?pageToken=` + query parameter `pageToken` to the server. Servers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` - parameter value for the next request. The server must omit or return `null` value for the + parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response. Servers that support pagination must return all results in a single response with the value - of `next-page-token` omitted or set to `null` if the query parameter `pageToken` is not set in the + of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the request. Servers that do not support pagination should ignore the `pageToken` parameter and return - all results in a single response. The `next-page-token` must be omitted or set to `null` - in the response. + all results in a single response. The `next-page-token` must be omitted from the response. Clients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results. From 2a0e672d2469e4d455c019d9e2112b23b4016e92 Mon Sep 17 00:00:00 2001 From: Rahil Chertara Date: Wed, 13 Mar 2024 21:26:54 -0700 Subject: [PATCH 4/4] make next-page-token allow null --- open-api/rest-catalog-open-api.py | 4 ++-- open-api/rest-catalog-open-api.yaml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index ca3045bf7d0c..7bd97b69885f 100644 --- a/open-api/rest-catalog-open-api.py +++ b/open-api/rest-catalog-open-api.py @@ -78,8 +78,8 @@ class Namespace(BaseModel): class PageToken(BaseModel): - __root__: str = Field( - ..., + __root__: Optional[str] = Field( + None, description='An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server.\nServers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response.\nServers that support pagination must return all results in a single response with the value of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the request.\nServers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted from the response.\nClients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.', ) diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml index eb6efec1cb37..161d5e0fcff8 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -1631,6 +1631,7 @@ components: the end of the listing results. type: string + nullable: true TableIdentifier: type: object