Merge pull request #51 from ni/users/alweaver/advanced-query-api-review

API Review - Test Monitor Advanced Query Language

Author: alexweav

test-monitor/nitestmonitor.yml

@@ -632,6 +632,26 @@ definitions:
         type: array
         items:
           $ref: '#/definitions/ResultSortDefinitionObject'
+  AdvancedQuery:
+    title: Advanced Query Object for Test Data
+    type: object
+    properties:
+      filter:
+        description: The query filter, in Dynamic Linq
+        type: string
+        example: (operator == "user1") || ((programName != "MyProgram") && (totalTimeInSeconds < @0))
+      substitutions:
+        description: >-
+          Makes substitutions in the query filter expression. Substitutions for the query expression
+          are indicated by non-negative integers that are prefixed with the "at" symbol. Each
+          substitution in the given expression will be replaced by the element at the corresponding 
+          index (zero-based) in this list. For example, "@0" in the filter expression will be replaced with
+          the element at the zeroth index of the substitutions list.
+        type: array
+        items:
+          type: object
+        example:
+          - 2.5
   StepIdResultIdPair:
     title: Step Id / Result Id Pair
     type: object
@@ -1150,48 +1170,61 @@ paths:
           description: Not Found
           schema:
             $ref: '#/definitions/Error'
-  /v1/query-results:
+  /v2/query-results:
     post:
       tags: [results]
-      summary: Queries test results
-      description: Uses input criteria to filter and return test results. An empty request body queries all test results.
-      operationId: query-results
+      summary: Advanced Test Result Query
+      description: >-
+        Uses the Dynamic Linq query language to specify a filter and return
+        test results. An empty request body queries all test results.
+      operationId: query-results-v2
       x-ni-operation: queryResults
       x-ni-privilege: Read
       parameters:
         - in: body
           name: postBody
-          description: Result query object
+          description: Query filter
           required: false
           schema:
-            $ref: '#/definitions/TestResultQueryObject'
+            $ref: '#/definitions/AdvancedQuery'
         - in: query
           name: skip
+          description: >-
+            The number of matching results to skip when querying.
+            For example, if the query filter matches 100 results with a skip
+            value of 50 and a take value of 25, results 51 through 75 will be
+            returned.
           type: integer
           format: int32
           default: 0
           minimum: 0
         - in: query
           name: take
+          description: >-
+            The total number of results to return.
+            For example, if the query filter matches 100 results with a skip
+            value of 50 and a take value of 25, results 51 through 75 will be
+            returned.
           type: integer
           format: int32
-          default: -1
-          minimum: -1
+          default: 1000
+          minimum: 0
       responses:
         200:
           $ref: '#/responses/ResultsQueryResponse'
         401:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/results:
+  /v2/results:
     get:
       tags: [results]
       summary: Gets test results
       description: Gets a list of test results.
       operationId: get-results
       x-ni-operation: getResults
       x-ni-privilege: Read
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: query
           name: skip
@@ -1219,6 +1252,7 @@ paths:
       operationId: update-results
       x-ni-operation: updateResults
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1258,6 +1292,7 @@ paths:
       operationId: create-results
       x-ni-operation: createResults
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1284,14 +1319,15 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/results/{resultId}:
+  /v2/results/{resultId}:
     delete:
       tags: [results]
       summary: Deletes a test result
       description: Deletes the test result with the specified id. The request succeeds for result ids that do not exist.
       operationId: DeleteResult
       x-ni-operation: deleteResult
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: path
           name: resultId
@@ -1310,14 +1346,15 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/delete-results:
+  /v2/delete-results:
     post:
       tags: [results]
       summary: Deletes test results
       description: Deletes multiple test results in a single request.
       operationId: delete-results
       x-ni-operation: deleteResults
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1349,48 +1386,61 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/query-steps:
+  /v2/query-steps:
     post:
       tags: [steps]
-      summary: Queries test steps
-      description: Uses input criteria to filter and return test steps. An empty request body queries all test steps.
-      operationId: query-steps
+      summary: Advanced Test Step Query
+      description: >-
+        Uses the Dynamic Linq query language to specify a filter and return
+        test steps. An empty request body queries all test steps.
+      operationId: query-steps-v2
       x-ni-operation: querySteps
       x-ni-privilege: Read
       parameters:
         - in: body
           name: postBody
-          description: Step query object
+          description: Query filter
           required: false
           schema:
-            $ref: '#/definitions/TestStepQueryObject'
+            $ref: '#/definitions/AdvancedQuery'
         - in: query
           name: skip
+          description: >-
+            The number of matching steps to skip when querying.
+            For example, if the query filter matches 100 steps with a skip
+            value of 50 and a take value of 25, steps 51 through 75 will be
+            returned.
           type: integer
           format: int32
           default: 0
           minimum: 0
         - in: query
           name: take
+          description: >-
+            The total number of steps to return.
+            For example, if the query filter matches 100 steps with a skip
+            value of 50 and a take value of 25, steps 51 through 75 will be
+            returned.
           type: integer
           format: int32
-          default: -1
-          minimum: -1
+          default: 1000
+          minimum: 0
       responses:
         200:
           $ref: '#/responses/StepsQueryResponse'
         401:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/steps:
+  /v2/steps:
     get:
       tags: [steps]
       summary: Gets test steps
       description: Gets a list of test steps.
       operationId: get-steps
       x-ni-operation: getSteps
       x-ni-privilege: Read
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: query
           name: skip
@@ -1418,6 +1468,7 @@ paths:
       operationId: update-steps
       x-ni-operation: updateSteps
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1444,6 +1495,7 @@ paths:
       operationId: create-steps
       x-ni-operation: createSteps
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1465,14 +1517,15 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/results/{resultId}/steps/{stepId}:
+  /v2/results/{resultId}/steps/{stepId}:
     delete:
       tags: [steps]
       summary: Deletes a test step
       description: Deletes the test step with the specified id. The request succeeds for step ids that do not exist.
       operationId: DeleteStep
       x-ni-operation: deleteStep
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: path
           name: resultId
@@ -1496,14 +1549,15 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
-  /v1/delete-steps:
+  /v2/delete-steps:
     post:
       tags: [steps]
       summary: Deletes test steps
       description: Deletes multiple test steps in a single request.
       operationId: delete-steps
       x-ni-operation: deleteSteps
       x-ni-privilege: Write
+      x-ni-oldest-compatible-version: 1
       parameters:
         - in: body
           name: requestBody
@@ -1540,3 +1594,73 @@ paths:
           $ref: '#/responses/Unauthorized'
         default:
           $ref: '#/responses/Error'
+  /v1/query-results:
+    post:
+      tags: [deprecated]
+      summary: Queries test results
+      description: Uses input criteria to filter and return test results. An empty request body queries all test results.
+      operationId: query-results
+      x-ni-operation: queryResults
+      x-ni-privilege: Read
+      deprecated: true
+      parameters:
+        - in: body
+          name: postBody
+          description: Result query object
+          required: false
+          schema:
+            $ref: '#/definitions/TestResultQueryObject'
+        - in: query
+          name: skip
+          type: integer
+          format: int32
+          default: 0
+          minimum: 0
+        - in: query
+          name: take
+          type: integer
+          format: int32
+          default: -1
+          minimum: -1
+      responses:
+        200:
+          $ref: '#/responses/ResultsQueryResponse'
+        401:
+          $ref: '#/responses/Unauthorized'
+        default:
+          $ref: '#/responses/Error'
+  /v1/query-steps:
+    post:
+      tags: [deprecated]
+      summary: Queries test steps
+      description: Uses input criteria to filter and return test steps. An empty request body queries all test steps.
+      operationId: query-steps
+      x-ni-operation: querySteps
+      x-ni-privilege: Read
+      deprecated: true
+      parameters:
+        - in: body
+          name: postBody
+          description: Step query object
+          required: false
+          schema:
+            $ref: '#/definitions/TestStepQueryObject'
+        - in: query
+          name: skip
+          type: integer
+          format: int32
+          default: 0
+          minimum: 0
+        - in: query
+          name: take
+          type: integer
+          format: int32
+          default: -1
+          minimum: -1
+      responses:
+        200:
+          $ref: '#/responses/StepsQueryResponse'
+        401:
+          $ref: '#/responses/Unauthorized'
+        default:
+          $ref: '#/responses/Error'