From cc0b845af46219c7ea8eb5d43fc736af627f233b Mon Sep 17 00:00:00 2001
From: Paul Horton <phorton@sonatype.com>
Date: Thu, 12 Mar 2026 08:54:51 +0000
Subject: [PATCH 1/5] feat: Add opaque pagination to `/products` endpoint (for
 review and discussion)

Signed-off-by: Paul Horton <phorton@sonatype.com>
---
 spec/openapi.yaml | 88 +++++++++++++++++++++++++++++------------------
 1 file changed, 55 insertions(+), 33 deletions(-)

diff --git a/spec/openapi.yaml b/spec/openapi.yaml
index 6a2f8e7..ad4de4d 100644
--- a/spec/openapi.yaml
+++ b/spec/openapi.yaml
@@ -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:
@@ -157,10 +157,10 @@ paths:
         match.
       operationId: queryTeaProducts
       parameters:
-        - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
-        - $ref: "#/components/parameters/id-type"
-        - $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"
@@ -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.
       required:
-        - timestamp
-        - pageStartIndex
-        - pageSize
-        - totalResults
+        - nextPageToken
 
     paginated-product-response:
       type: object
@@ -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:
@@ -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.
       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
+    # 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
+        default: name
+
     #
     # Query by identifier
     #

From dffef69437796e7ebf657eec5376ba4c9ad832d7 Mon Sep 17 00:00:00 2001
From: Paul Horton <phorton@sonatype.com>
Date: Thu, 12 Mar 2026 09:10:14 +0000
Subject: [PATCH 2/5] removed typo...

Signed-off-by: Paul Horton <phorton@sonatype.com>
---
 spec/openapi.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/openapi.yaml b/spec/openapi.yaml
index ad4de4d..6d149f3 100644
--- a/spec/openapi.yaml
+++ b/spec/openapi.yaml
@@ -1,4 +1,4 @@
-open# $schema: https://spec.openapis.org/oas/3.1/schema-base/2025-02-13
+# $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:

From 09e629982d47085c8b69125689f14aeda6ba6112 Mon Sep 17 00:00:00 2001
From: Paul Horton <phorton@sonatype.com>
Date: Thu, 12 Mar 2026 10:07:37 +0000
Subject: [PATCH 3/5] Added `hasNext` into `pagination-details` schema

`reuslts` is now required in Products Response

Signed-off-by: Paul Horton <phorton@sonatype.com>
---
 spec/openapi.yaml | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/spec/openapi.yaml b/spec/openapi.yaml
index 6d149f3..5ef652f 100644
--- a/spec/openapi.yaml
+++ b/spec/openapi.yaml
@@ -1468,27 +1468,24 @@ components:
     pagination-details:
       type: object
       properties:
+        hasNext:
+          type: boolean
+          description: |
+            A flag (to aid clients) to know whether there is a next page of results to fetch. 
+            
+            `nextPageToken` will always be supplied, hence this hint is included to aid clients.
+          default: false
         nextPageToken:
           type: string
-          nullable: true
+          nullable: false
           description: |
-            A token to retrieve the next page. If this field is omitted or empty, 
-            there are no more pages to retrieve.
+            A token that can be used in a following request to retrieve the next page or results.
+
+            It must always be supplied in responses.
       required:
+        - hasNext
         - nextPageToken
 
-    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-response:
       type: object
       description: A paginated response containing TEA Product Releases
@@ -1566,6 +1563,8 @@ components:
                     type: array
                     items:
                       $ref: "#/components/schemas/product"
+                required:
+                  - results
     paginated-product-release:
       description: A paginated response containing TEA Product Releases
       content:

From 13633f5b35da092f7d9aaf370fdf9481dd6cfb65 Mon Sep 17 00:00:00 2001
From: Paul Horton <phorton@sonatype.com>
Date: Thu, 12 Mar 2026 15:51:26 +0000
Subject: [PATCH 4/5] Added pagination to further endpoints

Signed-off-by: Paul Horton <phorton@sonatype.com>
---
 spec/openapi.yaml | 186 +++++++++++++++++++++++++++++-----------------
 1 file changed, 117 insertions(+), 69 deletions(-)

diff --git a/spec/openapi.yaml b/spec/openapi.yaml
index 5ef652f..946dd5d 100644
--- a/spec/openapi.yaml
+++ b/spec/openapi.yaml
@@ -52,8 +52,10 @@ paths:
           description: UUID of TEA Product in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
-        - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-product-release"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
           $ref: "#/components/responses/paginated-product-release"
@@ -116,10 +118,10 @@ paths:
       description: Returns a list of TEA product releases. Note that multiple product releases may match.
       operationId: queryTeaProductReleases
       parameters:
-        - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
-        - $ref: "#/components/parameters/id-type"
-        - $ref: "#/components/parameters/id-value"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-product-release"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
           $ref: "#/components/responses/paginated-product-release"
@@ -203,15 +205,13 @@ paths:
           description: UUID of TEA Component in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
+        - $ref: "#/components/parameters/page-size"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-component-release"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
-          description: Requested Releases of TEA Component found and returned
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  "$ref": "#/components/schemas/release"
+          $ref: "#/components/responses/paginated-component-release"
         '400':
           $ref: "#/components/responses/400-invalid-request"
         '404':
@@ -247,10 +247,10 @@ paths:
       description: Returns a list of TEA components. Note that multiple components may match.
       operationId: queryTeaComponents
       parameters:
-        - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
-        - $ref: "#/components/parameters/id-type"
-        - $ref: "#/components/parameters/id-value"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-component"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
           $ref: "#/components/responses/paginated-component"
@@ -263,10 +263,10 @@ paths:
       description: Returns a list of TEA component releases. Note that multiple component releases may match.
       operationId: queryTeaComponentReleases
       parameters:
-        - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
-        - $ref: "#/components/parameters/id-type"
-        - $ref: "#/components/parameters/id-value"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-component"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
           $ref: "#/components/responses/paginated-component-release"
@@ -381,15 +381,13 @@ paths:
           description: UUID of TEA Component Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
+        - $ref: "#/components/parameters/page-size"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-collection"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
-          description: Requested TEA Collection found and returned
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  "$ref": "#/components/schemas/collection"
+          $ref: "#/components/responses/paginated-collection"
         '400':
           $ref: "#/components/responses/400-invalid-request"
         '404':
@@ -407,15 +405,13 @@ paths:
           description: UUID of TEA Product Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
+        - $ref: "#/components/parameters/page-size"
+        - $ref: "#/components/parameters/page-token"
+        - $ref: "#/components/parameters/sort-field-collection"
+        - $ref: "#/components/parameters/sort-order"
       responses:
         '200':
-          description: Requested TEA Collection found and returned
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  "$ref": "#/components/schemas/collection"
+          $ref: "#/components/responses/paginated-collection"
         '400':
           $ref: "#/components/responses/400-invalid-request"
         '404':
@@ -1486,41 +1482,6 @@ components:
         - hasNext
         - nextPageToken
 
-    paginated-product-release-response:
-      type: object
-      description: A paginated response containing TEA Product Releases
-      allOf:
-        - $ref: "#/components/schemas/pagination-details"
-        - type: object
-          properties:
-            results:
-              type: array
-              items:
-                $ref: "#/components/schemas/productRelease"
-
-    paginated-component-response:
-      type: object
-      description: A paginated response containing TEA Components
-      allOf:
-        - $ref: "#/components/schemas/pagination-details"
-        - type: object
-          properties:
-            results:
-              type: array
-              items:
-                $ref: "#/components/schemas/component"
-
-    paginated-component-release-response:
-      type: object
-      description: A paginated response containing TEA Component Releases
-      allOf:
-        - $ref: "#/components/schemas/pagination-details"
-        - type: object
-          properties:
-            results:
-              type: array
-              items:
-                $ref: "#/components/schemas/release"
   responses:
     204-common-delete:
       description: Object deleted successfully
@@ -1570,19 +1531,62 @@ components:
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/paginated-product-release-response"
+            allOf:
+              - $ref: "#/components/schemas/pagination-details"
+              - type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/productRelease"
+                required:
+                  - results
     paginated-component:
       description: A paginated response containing TEA Components
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/paginated-component-response"
+            allOf:
+              - $ref: "#/components/schemas/pagination-details"
+              - type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/component"
+                required:
+                  - results
     paginated-component-release:
       description: A paginated response containing TEA Component Releases
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/paginated-component-release-response"
+            allOf:
+              - $ref: "#/components/schemas/pagination-details"
+              - type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/release"
+                required:
+                  - results
+    paginated-collection:
+      description: A paginated response containing TEA Collections
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/pagination-details"
+              - type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/collection"
+                required:
+                  - results
+                    
   parameters:
     # Pagination
     page-size:
@@ -1617,6 +1621,38 @@ components:
           - desc
         default: asc
     # Pagination Sort Fields per TEA Object Type
+    sort-field-collection:
+      name: sortField
+      description: The field by which to sort the results.
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - version
+        default: version
+    sort-field-component:
+      name: sortField
+      description: The field by which to sort the results.
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - name
+        default: name
+    sort-field-component-release:
+      name: sortField
+      description: The field by which to sort the results.
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - createdDate
+          - releaseDate
+          - version
+        default: createdDate
     sort-field-product:
       name: sortField
       description: The field by which to sort the results.
@@ -1627,6 +1663,18 @@ components:
         enum:
           - name
         default: name
+    sort-field-product-release:
+      name: sortField
+      description: The field by which to sort the results.
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - createdDate
+          - releaseDate
+          - version
+        default: createdDate
 
     #
     # Query by identifier

From 4a34e6f4be2ce133d13978235378adca5bbffc4d Mon Sep 17 00:00:00 2001
From: Paul Horton <phorton@sonatype.com>
Date: Fri, 13 Mar 2026 07:49:18 +0000
Subject: [PATCH 5/5] re-added `id-type` and `id-value` for result filtering

Signed-off-by: Paul Horton <phorton@sonatype.com>
---
 spec/openapi.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/spec/openapi.yaml b/spec/openapi.yaml
index 946dd5d..4332a66 100644
--- a/spec/openapi.yaml
+++ b/spec/openapi.yaml
@@ -118,6 +118,10 @@ paths:
       description: Returns a list of TEA product releases. Note that multiple product releases may match.
       operationId: queryTeaProductReleases
       parameters:
+        # For result filtering
+        - $ref: "#/components/parameters/id-type"
+        - $ref: "#/components/parameters/id-value"
+        # For pagination
         - $ref: "#/components/parameters/page-size"
         - $ref: "#/components/parameters/page-token"
         - $ref: "#/components/parameters/sort-field-product-release"
@@ -159,6 +163,10 @@ paths:
         match.
       operationId: queryTeaProducts
       parameters:
+        # For result filtering
+        - $ref: "#/components/parameters/id-type"
+        - $ref: "#/components/parameters/id-value"
+        # For pagination
         - $ref: "#/components/parameters/page-size"
         - $ref: "#/components/parameters/page-token"
         - $ref: "#/components/parameters/sort-field-product"
@@ -247,6 +255,10 @@ paths:
       description: Returns a list of TEA components. Note that multiple components may match.
       operationId: queryTeaComponents
       parameters:
+        # For result filtering
+        - $ref: "#/components/parameters/id-type"
+        - $ref: "#/components/parameters/id-value"
+        # For pagination
         - $ref: "#/components/parameters/page-size"
         - $ref: "#/components/parameters/page-token"
         - $ref: "#/components/parameters/sort-field-component"
@@ -263,6 +275,10 @@ paths:
       description: Returns a list of TEA component releases. Note that multiple component releases may match.
       operationId: queryTeaComponentReleases
       parameters:
+        # For result filtering
+        - $ref: "#/components/parameters/id-type"
+        - $ref: "#/components/parameters/id-value"
+        # For pagination
         - $ref: "#/components/parameters/page-size"
         - $ref: "#/components/parameters/page-token"
         - $ref: "#/components/parameters/sort-field-component"