Repository navigation
Spec: Add shared pagination definitions for Polaris APIs #6028
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.
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
base: main
Are you sure you want to change the base?
Changes from 1 commit
cfe35ed
9cded34
d4df9ed
cf08c5a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,65 @@ | ||||||||
| # | ||||||||
| # Licensed to the Apache Software Foundation (ASF) under one | ||||||||
| # or more contributor license agreements. See the NOTICE file | ||||||||
| # distributed with this work for additional information | ||||||||
| # regarding copyright ownership. The ASF licenses this file | ||||||||
| # to you under the Apache License, Version 2.0 (the | ||||||||
| # "License"); you may not use this file except in compliance | ||||||||
| # with the License. You may obtain a copy of the License at | ||||||||
| # | ||||||||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||||||||
| # | ||||||||
| # Unless required by applicable law or agreed to in writing, | ||||||||
| # software distributed under the License is distributed on an | ||||||||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||||||||
| # KIND, either express or implied. See the License for the | ||||||||
| # specific language governing permissions and limitations | ||||||||
| # under the License. | ||||||||
| # | ||||||||
|
|
||||||||
| # Pagination definitions shared by the Polaris-specific APIs: the Polaris catalog APIs and the | ||||||||
| # management APIs. A list operation references the two parameters and uses the PageToken schema for | ||||||||
| # the token in its response. The response field is named in the style of the API it belongs to: | ||||||||
| # `next-page-token` in the catalog APIs, `nextPageToken` in the management APIs. | ||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could we leave the response field names to the individual API specs? This file can focus on the pagination rules they share.
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done, each API spec names its own field. |
||||||||
| # | ||||||||
| # These rules differ from the Iceberg REST Catalog API, where a server must return all results when | ||||||||
| # the request has no `pageToken`. Operations defined by the Iceberg REST Catalog API keep its rules. | ||||||||
|
|
||||||||
| --- | ||||||||
| components: | ||||||||
| parameters: | ||||||||
| PolarisPageToken: | ||||||||
| name: pageToken | ||||||||
| in: query | ||||||||
| required: false | ||||||||
| description: > | ||||||||
| The page token from the previous response of the same list operation, sent unchanged. Omit it | ||||||||
| to get the first page. | ||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could we specify that the server returns
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could we require clients to keep the parent, filters, and sort order the same, while allowing pageSize to change? Should the server return 400 if those other parameters change?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done. The
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agreed, and JB raised the same point on dev@. The description now says that with a page token the client sends the same path and query parameters as in the previous request, except For the server side I wrote "may" return 400 when the other parameters differ, not "must": today's tokens only carry the page size and the position, so the server can't tell that a filter changed without a change to the token format. |
||||||||
| schema: | ||||||||
| type: string | ||||||||
|
|
||||||||
| PolarisPageSize: | ||||||||
| name: pageSize | ||||||||
| in: query | ||||||||
| required: false | ||||||||
| description: > | ||||||||
| A hint for the largest number of results the client wants in one page. The server decides | ||||||||
| the actual page size, which may be smaller. | ||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could we say that the server configures the maximum page size and a client can ask for a smaller page? For example, if the server maximum is 100,
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, that's the intent. I changed I kept the qualifier "a server that paginates", because the last rule still lets a server that doesn't paginate return everything in one response, as in the Iceberg spec.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "at most" SGTM |
||||||||
| schema: | ||||||||
| type: integer | ||||||||
| minimum: 1 | ||||||||
|
|
||||||||
| schemas: | ||||||||
| PolarisPageToken: | ||||||||
| description: | | ||||||||
| An opaque token that continues a list operation. Clients must not interpret it. | ||||||||
|
|
||||||||
| - Any response may be paginated. A client must always check for a page token in the | ||||||||
| response and, when one is present, send it unchanged as the `pageToken` query parameter | ||||||||
| to get the next page. The server omits the page token from the last page. A client must | ||||||||
| treat a missing or `null` page token as the end of the results. | ||||||||
| - A client does not need to send `pageToken` or `pageSize` to start paginating. The server | ||||||||
| may paginate a response to a request that has neither. | ||||||||
| - The server decides the page size. A page may hold fewer results than `pageSize`. | ||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Minor: I think we've explain the rule already in
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agreed. With |
||||||||
| - A server that does not paginate returns all results in one response, with no page token. | ||||||||
| type: string | ||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor: we don't have to enumerate them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.