Using the QuerySurge Base REST API – Customer Support

Versions:7.0+

API Overview

The QuerySurge REST API breaks out into two areas:

The QuerySurge Base REST API - a lightweight execution API, which allows users to drive QuerySurge execution externally from QuerySurge. All instances of QuerySurge come bundled with the base API.
The QuerySurge DevOps REST API - a full DevOps API supporting the majority of QuerySurge functions such as creation/modification/deletion of assets in an API context.

The QuerySurge REST API requires no supplemental installation; it can be accessed through any standard HTTP tool (e.g. Postman) or HTTP-accessible scripting tool.

REST documentation is included in QuerySurge; you can access it at the following URL:

http://<your-QuerySurge-server>:<port>/QuerySurge/rest-docs

A sample URL with QuerySurge deployed on server 'myserver.mycompany.com' on port 8080 looks like:

http://myserver.mycompany.com:8080/QuerySurge/rest-docs

Base REST API

The following APIs are available at all license levels:

GET /project/{projectId}/status/scenario/{guid}
PUT /project/{projectId}/snippet/{id}
POST /project/{projectId}/execute/suite
POST /auth/login
POST /auth/logout

REST API Transaction Workflow

In order to use any of the REST APIs, you need to issue your calls in the proper transactional sequence (from an application/API perspective). This means that you'll need to execute an authentication/login call first, then issue the API call(s) that you are interested in, followed by logging out.

Basic Scripts for Starting Test Runs

The simplest use case that involves using the Base REST API is triggering the execution of a Test Suite directly from the Windows PowerShell or a Linux terminal (Shell). This use case involves the following:

REST API call for Authentication

To authenticate with the QuerySurge server will will utilize the API endpoint /auth/login.

Figure 1

Figure 1 demonstrates usage of Invoke-WebRequest powershell cmdlet to send HTTP request to the QuerySurge server. As seen in the command, we are passing a body parameter which contains the username and password for the account which we are authenticating with. Running the command, authenticates the user and returns a range of information about the call. The information we are interested in is the Content field which is a JSON object that holds the sessionId (in our case its 'bc8deae2-80d1-47fc-baec-a4d4e3513712'). This is an Authorization token used to validate a user when accessing any of the QuerySurge REST API. This is required to make further REST calls during this login session.

REST API call to run a Test Suite

In order to run a Test Suite we will utilize the API endpoint /project/{projectId}/execute/suite.

Figure 2

In Figure 2 we pass in the sessionId obtained from the authorization step above as a header parameter to the api. The header variable used to store this is called 'X-QS-AUTH'. We also need to pass the id associated with the test suite we want to run and the scenario name. These appear as parameters in the request url. In Figure 2 we pass in Test Suite Id '1840' with scenario name 'Regression'. When the API is called, a scenario named 'Regression' is created in QuerySurge and is scheduled to run immediately. The API returns the execution guid as part of its response (which in this example is '1d0e34db-19d4-4c2b-8d5c-cbfba8eec1db'). This guid can be used to check on the status of the execution.

REST API call to Logout

Finally we make a call to /auth/logout to log the user out.

Figure 3

In Figure 3 we log the user out utilizing the same sessionId we obtained earlier. Upon successful logout the API returns a status code of 204.

At this point the sessionId we obtained in the login step ('bc8deae2-80d1-47fc-baec-a4d4e3513712') is no longer valid and cannot be used to make further API calls.

Advanced Event Driven Scripts

Invoking the REST API from a PowerShell terminal is useful to perform quick tests, however these scripts can be made even more powerful with additional logic.

Figure 4 shows an example of a PowerShell script that incorporates logic to determine when each Test Suite is ready to be run, based on whether the previous Test Suite has completed. It also incorporates kicking off multiple legs of an ETL process (two legs, in this illustration).

First, the script runs the initial ETL process. Once that is complete, it runs the Test Suite in QuerySurge that has been set up for that ETL. It then captures the Scenario execution guid that is returned (in a variable called $executionGuid) and uses that guid with the api /project/{projectId}/status/scenario/{guid} to check on the status of that run in QuerySurge. The script checks whether the Scenario has started, and once it has, it continues to check on the run status until the Scenario has completed. Once the first Scenario is completed, the second ETL process is run. Finally, the second Test Suite is executed, which runs the tests prepared for the second ETL leg.

This example shows how the different commands can be used together to build a comprehensive run script that effectively is incorporated into an ETL process.

Figure 4

The Base REST API gives users significant flexibility, supporting QuerySurge integration into a wide range of execution workflows, from functional/regression data testing workflows owned by Data Warehouse project teams to daily monitoring workflows owned by Operations teams. QuerySurge of course keeps results organized with full access to past runs, data drilldown and export, and results reporting. Scenarios that are run from the Base REST API appear in the QuerySurge user interface the same as user-initiated runs appear, so all of the data access features are available for these executions.

API Documentation

The QuerySurge REST API is further documented in the Knowledge Base, both from the perspective of standard API documentation as well as Use Case-based articles:

Articles in this section