From 316875c1b795310298a4174db1bc7eb5c3930aad Mon Sep 17 00:00:00 2001 From: Daniel Weeks Date: Tue, 5 Mar 2024 19:45:12 -0800 Subject: [PATCH] Clarify pagination description --- open-api/rest-catalog-open-api.py | 2 +- open-api/rest-catalog-open-api.yaml | 27 ++++++++++++++++++++------- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index 77dcad9cfba6..be1641eaf8f0 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.\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 or set to `null` in the response.\nClients must interpret either `null` or missing response value of `last-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..f9264f957168 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -1610,13 +1610,26 @@ 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. - - 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. + 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. + + 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` 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 `last-page-token` as + the end of the listing results. type: string TableIdentifier: