From c03cd91564e7c7eaa2ca0cc73708e1a303c7b9a1 Mon Sep 17 00:00:00 2001
From: Philip de Nier <philipn@rd.bbc.co.uk>
Date: Mon, 22 Jul 2024 11:18:52 +0100
Subject: [PATCH] api: allow flow segment paging using opaque key

Allow the next page link to include a "page" query parameter that allows
the next page to be retrieved. If the TAMS implementations uses "page"
then it will likely leave the "timerange" query parameter unchanged.

Marking this change as a feature rather than a breaking change because
clients should be treating the query parameters of a page link as opaque.

sem-ver: feature
---
 api/TimeAddressableMediaStore.yaml | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml
index 1aa28ee..203ed01 100644
--- a/api/TimeAddressableMediaStore.yaml
+++ b/api/TimeAddressableMediaStore.yaml
@@ -1179,13 +1179,18 @@ paths:
           description: Filter on object identifier.
           schema:
             type: string
+        - name: timerange
+          in: query
+          description: Return only the results in the timerange specified.
+          schema:
+            $ref: 'schemas/timerange.json'
         - name: reverse_order
           in: query
           description: Return segments in reverse time order.
           schema:
             default: false
             type: boolean
-        - $ref: '#/components/parameters/trait_timerange_paged_timerange'
+        - $ref: '#/components/parameters/trait_resource_paged_key'
         - $ref: '#/components/parameters/trait_paged_limit'
       responses:
         "200":
@@ -1235,13 +1240,18 @@ paths:
           description: Filter on object identifier.
           schema:
             type: string
+        - name: timerange
+          in: query
+          description: Return only the results in the timerange specified.
+          schema:
+            $ref: 'schemas/timerange.json'
         - name: reverse_order
           in: query
           description: Return segments in reverse time order.
           schema:
             default: false
             type: boolean
-        - $ref: '#/components/parameters/trait_timerange_paged_timerange'
+        - $ref: '#/components/parameters/trait_resource_paged_key'
         - $ref: '#/components/parameters/trait_paged_limit'
       responses:
         "200":
@@ -1267,6 +1277,10 @@ paths:
               description: The items are returned in reverse order.
               schema:
                 type: boolean
+            X-Paging-NextKey:
+              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
+              schema:
+                type: string
           content:
             application/json:
               schema:
@@ -1796,12 +1810,6 @@ components:
     trait_resource_info_head_404:
       description: Resource was not found.
   parameters:
-    trait_timerange_paged_timerange:
-      name: timerange
-      in: query
-      description: Return only the results in the timerange specified.
-      schema:
-        $ref: 'schemas/timerange.json'
     trait_paged_limit:
       name: limit
       in: query