Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 3 additions & 0 deletions spec/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,9 @@ Apache Polaris provides the following OpenAPI specifications:
- [oauth-tokens-api.yaml](polaris-catalog-apis/oauth-tokens-api.yaml) - Contains the specification for the
internal OAuth Token endpoint, extracted from the Apache Iceberg REST Catalog API.

- [polaris-pagination.yaml](polaris-pagination.yaml) - Defines the pagination parameters and page token
shared by the Polaris-specific list operations, in both the catalog and the management APIs.


## Generated Specification Files
The specification files in the generated folder are automatically created using OpenAPI bundling tools such as
Expand Down
68 changes: 68 additions & 0 deletions spec/polaris-pagination.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#
# 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. It may return fewer, even none, in a page that is not
the last; a client that gets a page with no results and a page token requests the next page
with that token. 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, `null`, or empty 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.
- A server that does not paginate returns all results in one response, with no page token.
type: string
Loading