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 3 commits
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,67 @@ | ||
| # | ||
| # 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. A list operation references the two | ||
| # parameters and uses the PageToken schema for the token in its response. | ||
| # | ||
| # 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, or send it empty, to get the first page. With a page token, the client sends the same | ||
| path and query parameters as in the previous request, except `pageSize`, which it may | ||
| change. The server returns `400 Bad Request` for a page token it cannot use, and may do so | ||
| when the other parameters differ from the previous request. | ||
| schema: | ||
| type: string | ||
|
|
||
| PolarisPageSize: | ||
| name: pageSize | ||
| in: query | ||
| required: false | ||
| description: > | ||
| The largest number of results the client wants in one page. A server that paginates returns | ||
| at most this many results in a page, and fewer when its own maximum page size is smaller. | ||
| Without `pageSize`, the server chooses the page size. | ||
| schema: | ||
| type: integer | ||
| minimum: 1 | ||
|
|
||
| schemas: | ||
| PolarisPageToken: | ||
| description: | | ||
| An opaque token that continues a list operation. Clients must not interpret it. | ||
| - Any response of an operation that uses these definitions 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 | ||
|
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. Technically an empty token fits here too since the doc above (line 35) equates empty tokens with missing tokens.
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. Good catch. The rule now reads "a missing, |
||
| 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. | ||
| - 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.
maximum page sizeis a fuzzy term. In certain situations the size may be the number of entries, in others the number of bytes.I'd prefer to avoid this complication in the spec and just say "The server may return fewer items, even zero items. If zero items are returned the client should request yet another page using the fresh page token from the empty response". (feel free to rephrase / edit).
The zero case is actualized in #5544
#5544 (comment)
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.
Agreed, I dropped "maximum page size".
pageSizenow says the server returns at most that many results and may return fewer, even none, in a page that is not the last; a client that gets an empty page with a page token requests the next page with it. The first rule already makes a missing token the only end-of-results signal, so the zero-results case from #5544 is covered.