Skip to content

feat: Add opaque pagination #231

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

Open
madpah wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: Add opaque pagination #231

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cc0b845
feat: Add opaque pagination to `/products` endpoint (for review and d…
madpah Mar 12, 2026
dffef69
removed typo...
madpah Mar 12, 2026
09e6299
Added `hasNext` into `pagination-details` schema
madpah Mar 12, 2026
13633f5
Added pagination to further endpoints
madpah Mar 12, 2026
4a34e6f
re-added `id-type` and `id-value` for result filtering
madpah Mar 13, 2026
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
88 changes: 55 additions & 33 deletions spec/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# $schema: https://spec.openapis.org/oas/3.1/schema-base/2025-02-13
open# $schema: https://spec.openapis.org/oas/3.1/schema-base/2025-02-13
openapi: 3.1.1
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
info:
Expand Down Expand Up @@ -157,10 +157,10 @@ paths:
match.
operationId: queryTeaProducts
parameters:
- $ref: "#/components/parameters/page-offset"
- $ref: "#/components/parameters/page-size"
- $ref: "#/components/parameters/id-type"
Comment thread
madpah marked this conversation as resolved.
- $ref: "#/components/parameters/id-value"
- $ref: "#/components/parameters/page-token"
- $ref: "#/components/parameters/sort-field-product"
- $ref: "#/components/parameters/sort-order"
responses:
'200':
$ref: "#/components/responses/paginated-product"
Expand Down Expand Up @@ -1468,26 +1468,14 @@ components:
pagination-details:
type: object
properties:
timestamp:
nextPageToken:
type: string
format: date-time
example: '2024-03-20T15:30:00Z'
pageStartIndex:
type: integer
format: int64
default: 0
pageSize:
type: integer
format: int64
default: 100
totalResults:
type: integer
format: int64
nullable: true
description: |
A token to retrieve the next page. If this field is omitted or empty,
there are no more pages to retrieve.
Comment thread
madpah marked this conversation as resolved.
Outdated
required:
- timestamp
- pageStartIndex
- pageSize
- totalResults
- nextPageToken

paginated-product-response:
type: object
Expand Down Expand Up @@ -1568,7 +1556,16 @@ components:
content:
application/json:
schema:
$ref: "#/components/schemas/paginated-product-response"
type: object
description: A paginated response containing TEA Products
allOf:
- $ref: "#/components/schemas/pagination-details"
- type: object
properties:
results:
type: array
items:
$ref: "#/components/schemas/product"
paginated-product-release:
description: A paginated response containing TEA Product Releases
content:
Expand All @@ -1589,24 +1586,49 @@ components:
$ref: "#/components/schemas/paginated-component-release-response"
parameters:
# Pagination
page-offset:
name: pageOffset
description: Pagination offset
page-size:
name: pageSize
description: The maximum number of results to return.
in: query
required: false
schema:
type: integer
format: int64
default: 0
page-size:
name: pageSize
description: Pagination offset
minimum: 1
maximum: 100
default: 25
page-token:
name: pageToken
description: |
An opaque token used to retrieve the next page of results.
This should be copied exactly from the `nextPageToken` field of a previous response.
Copy link
Copy Markdown

@Mehrn0ush Mehrn0ush May 5, 2026

Choose a reason for hiding this comment

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

Can we define how pageToken interacts with the other query parameters?

For cursor/token pagination, clients need to know whether pageToken already encapsulates the original query state, including filters, sortField, sortOrder, and possibly pageSize.

For example, if the first request uses:

sortField=createdDate&sortOrder=desc&pageSize=25

and the next request sends:

pageToken=...&sortField=version&sortOrder=asc&pageSize=100

what should the server do?

Possible options:

  1. The server MUST ignore sortField, sortOrder, filters, and pageSize when pageToken is present.
  2. The server MUST return 400 if parameters conflict with the state encoded in pageToken.
  3. The client MUST repeat the same parameters, and mismatch is an invalid request.

I think the spec should choose one behavior before v1.0 to avoid incompatible implementations. Defining this behavior now will ensure forward compatibility and consistent behavior across different TEA server implementations.

in: query
required: false
schema:
type: integer
format: int64
default: 100
type: string
sort-order:
name: sortOrder
description: The direction of the sort.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
Copy link
Copy Markdown

@Mehrn0ush Mehrn0ush May 5, 2026

Choose a reason for hiding this comment

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

I noticed sortOrder defaults to asc globally. Would it be worth considering resource-specific defaults instead?

For security-related resources like product/component releases (often sorted by createdDate) or collections (sorted by version), consumers typically expect the most recent data first (newest-to-oldest).

If a universal asc default is preferred for simplicity, perhaps we could add a small note in the description to help set expectations for implementers/consumers.

# Pagination Sort Fields per TEA Object Type
sort-field-product:
name: sortField
description: The field by which to sort the results.
in: query
required: false
schema:
type: string
enum:
- name
Copy link
Copy Markdown

@Mehrn0ush Mehrn0ush May 5, 2026

Choose a reason for hiding this comment

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

sort-field-component:
enum:
- name

and

sort-field-product:
enum:
- name

If name is the default sort field for products and components, do we also need to specify whether names are unique within a TEA server?

If names are not guaranteed to be unique, token pagination still needs a deterministic secondary ordering, such as UUID. If names are intended to be unique, that constraint should probably be documented in the corresponding product/component schema descriptions.

default: name

#
# Query by identifier
#
Expand Down