ODM-12912: Update runs/by/group endpoints for cursor-based pagination (#499)

Author: natalyatodorova

openapi/v1/expressionCurator.yaml

@@ -431,7 +431,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n * pageLimit` until the `resultsExhausted` response field is true.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchExpressionRunsAsCurator
       parameters:
@@ -441,14 +441,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -461,7 +458,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}

openapi/v1/expressionUser.yaml

@@ -432,7 +432,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n * pageLimit` until the `resultsExhausted` response field is true.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchExpressionRunsAsUser
       parameters:
@@ -442,14 +442,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -462,7 +459,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}
@@ -670,6 +667,8 @@ components:
       $ref: "./schemas/common/ResponseFormat.yaml"
     RunFilter:
       $ref: "./schemas/common/RunFilter.yaml"
+    RunsResponse:
+      $ref: "./schemas/common/RunsResponse.yaml"
     SignalRun:
       $ref: "./schemas/common/SignalRun.yaml"
   securitySchemes:

openapi/v1/flowCytometryCurator.yaml

@@ -438,7 +438,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchFlowCytometryRunsAsCurator
       parameters:
@@ -448,14 +448,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -468,7 +465,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}

openapi/v1/flowCytometryUser.yaml

@@ -438,7 +438,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchFlowCytometryRunsAsUser
       parameters:
@@ -448,14 +448,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -468,7 +465,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}
@@ -676,6 +673,8 @@ components:
       $ref: "./schemas/common/ResponseFormat.yaml"
     RunFilter:
       $ref: "./schemas/common/RunFilter.yaml"
+    RunsResponse:
+      $ref: "./schemas/common/RunsResponse.yaml"
     SignalRun:
       $ref: "./schemas/common/SignalRun.yaml"
   securitySchemes:

openapi/v1/schemas/common/RunsResponse.yaml

@@ -1,27 +1,16 @@
 example:
-  experiment: experiment
-  warnings:
-  - warnings
-  - warnings
-  versionChainId: versionChainId
-  runs:
-  -
-  -
+  cursor: "1"
+  data:
+    - runId: "1"
+      sampleSourceId: "exp4-human-100well.ATATCCTACTACTTAACTAG"
+    - runId: "2"
+      sampleSourceId: "exp4-human-100well.TTACCTAAGTTTGATATATT"
 properties:
-  runs:
-    items:
-      $ref: "#/components/schemas/SignalRun"
-    type: array
-  experiment:
+  cursor:
     type: string
-  warnings:
+  data:
     items:
-      type: string
+      properties: { }
+      type: object
     type: array
-  versionChainId:
-    type: string
 type: object
-components:
-  schemas:
-    SignalRun:
-      $ref: "./SignalRun.yaml"

openapi/v1/variantCurator.yaml

@@ -463,7 +463,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchVariantRunsAsCurator
       parameters:
@@ -473,14 +473,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -493,7 +490,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}

openapi/v1/variantUser.yaml

@@ -464,7 +464,7 @@ paths:
     get:
       description: |+
         ## Paging
-        For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results.
+        For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result.
 
       operationId: searchVariantRunsAsUser
       parameters:
@@ -474,14 +474,11 @@ paths:
         required: true
         schema:
           type: string
-      - description: "Show the page {pageOffset+1} results from the start of the results.\
-          \ E.g. 100 will show a page of results  starting from the 101st result.\
-          \ The default value is 0."
+      - description: The page tag to resume results from (see paging above).
         in: query
-        name: pageOffset
+        name: cursor
         schema:
-          format: int32
-          type: integer
+          type: string
       - description: Maximum number of results to return per page (see Paging above).
           This value must be between 0 and 2000 (inclusive). The default is 2000.
         in: query
@@ -494,7 +491,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListResponse"
+                $ref: "#/components/schemas/RunsResponse"
           description: The request was successful. The returned value is the object.
         "400":
           content: {}
@@ -698,6 +695,8 @@ components:
       $ref: "./schemas/common/ResponseFormat.yaml"
     RunFilter:
       $ref: "./schemas/common/RunFilter.yaml"
+    RunsResponse:
+      $ref: "./schemas/common/RunsResponse.yaml"
     SignalRun:
       $ref: "./schemas/common/SignalRun.yaml"
     VariantItem: