Skip to content

Clarify pagination description #9872

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
danielcweeks wants to merge 1 commit into from
Closed

Clarify pagination description #9872

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion open-api/rest-catalog-open-api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.',
)


Expand Down
27 changes: 20 additions & 7 deletions open-api/rest-catalog-open-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

@rahil-c rahil-c Mar 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does the service distinguish this case from the initial request when pageToken is empty, but we still return the number of items determined by pageSize?

Copy link
Contributor Author

@danielcweeks danielcweeks Mar 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If no token is provided, I don't think pageSize makes sense because there's no guaranteed ordering. I think it's correct to say that if pageToken is not present, all results are returned.

of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the
Copy link
Contributor

@rahil-c rahil-c Mar 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of setting the next-page-token to null we can also just omit this from the response right?

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
Copy link
Contributor

@rahil-c rahil-c Mar 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there is no field called last-page-token we should just refer to this as next-page-token instead.

the end of the listing results.
type: string

TableIdentifier:
Expand Down