Articles in this section

Porting from CLI To Rest API

As QuerySurge is deprecating Command Line Interface (CLI), users are strongly encouraged to transition to the REST API for all interactions with QuerySurge. The REST API not only encompasses all functionalities previously available through the CLI, but also offers expanded capabilities and greater flexibility for integration and automation.

This article will walkthrough a common example of using the CLI to drive QuerySurge.

Overview

The CLI gets installed as a utility jar file during the time of QuerySurge installation. The utility exposes certain commands with their own set of parameters. Users can call these commands via a Windows shell or a Linux terminal to drive QuerySurge execution. The REST API however does not need any further installation. When QuerySurge is installed, the REST APIs are enabled. Users can use any scripting tool capable of making REST calls to drive QuerySurge execution via the REST APIs.

Lets walk through an example of executing a transaction in QuerySurge using both the Command Line Interface (CLI) and the REST API. This comparison will help illustrate the key differences between the two approaches. We will first demonstrate in Windows followed by corresponding example in Linux.

Execute a scenario and output the scenario execution GUID

Windows (CLI)

In order to execute a scenario using QuerySurge CLI, a typical script would look like the Sample code shown below. We use the runTestSuiteById command and the parameters include:

  • cliPath: the location of the installed CLI JAR utility

  • host and port: the hostname and port of the QuerySurge Application Server

  • username and password: credentials for QuerySurge authentication

  • projectId and suiteId: identifiers for the project and test suite to be executed

@echo off
;: ' ********************* START OF CONFIGURATION VARIABLES ************************
set cliPath=C:\Program Files\QuerySurge\cli\qscli
set hostname=127.0.0.1
set port=80
set username=admin
set password=admin
set projectId=1
set suiteId=1
;: ' ********************* END OF CONFIGURATION VARIABLES **************************

;: Execute a QuerySurge Scenario for each of the identified Suites by Suite ID
echo Running Suite %suiteId%
call "%cliPath%" runTestSuiteById --hostname %hostname% --port %port% --username %username% --password %password% --projectId %projectId% %suiteId%

echo "Done!"

CLI: Sample Script (Windows)

This script can be saved in a batch file with any given name such as Sample.bat and can be executed directly from the Windows Command Prompt as illustrated in Figure 1 below. Upon execution the utility internally authenticates the user, initiates the scenario execution, and returns a unique scenario execution identifier in plain text. In this case the identifier is e063043e-0cf9-4786-8010-1cb331c941a6.

Figure 1: Running a CLI from a command prompt

 

Windows (REST API)

To execute a scenario using the REST API, we will utilize PowerShell although any tool capable of making HTTP calls can be used. The parameters needed are same as the CLI with the exception of cliPath.

# ' ********************* START OF CONFIGURATION VARIABLES ************************
$hostname = "localhost"
$port = 8080
$username = "admin"
$password = "admin"
$projectId = 1
$scenarioName = "MyScenario"
$suiteId = 1
# ' ********************* END OF CONFIGURATION VARIABLES **************************

 

Unlike the CLI, the REST APIs in QuerySurge can only be invoked once the user has been authenticated, also called the login step. This is described in the code snipped below. We utilize Powershell command Invoke-RestMethod to make http calls although any tool capable of making http requests can be used. The command requires the following parameters in order to make the http request:

  • URI - the URL or endpoint we are sending request to, in this case it is the value of the $uri variable which is http://localhost:8080/QuerySurge/api/auth/login with the $uri string interpolated.
  • Method - the http method to use. POST in this case.
  • Headers - header content.
  • Content Type - tells the server what kind of data you are sending.
  • Body - represents the payload of the http request. In this context the body is a json object with the structure {"username": string, "password": string, "globalLogin": boolean}. This payload is used to supply user credentials. The username and password fields contain the user's login information, while the globalLogin flag indicates whether the login should be treated as a global session (true) or not (false).

We execute the Invoke-RestMethod and upon successful authentication, the endpoint returns a JSON object which consists of the session ID, which we store in the $sessionId variable.

# 1. Login
$uri = "http://{0}:{1}/QuerySurge/api/auth/login" -f $hostname, $port
$login = Invoke-RestMethod -Uri $uri -Method Post -Headers @{ "accept" = "application/json" } -ContentType "application/json" -Body "{`"username`":`"$username`",`"password`":`"$password`",`"globalLogin`":false}"
$sessionId = $login.sessionId

REST API: Login 

Next, we execute the scenario by calling the /api/project/{projectId}/execute/suite endpoint.

The -Uri parameter includes the required identifiers such as the project ID, suite ID, and scenario name. To authenticate the request, the -Headers parameter is configured to include a custom header, "X-QS-AUTH", whose value is the session ID ($sessionId) obtained during the authentication step.

If the parameters are valid, the API queues the scenario for execution and returns a JSON response. This response includes a guid field which represents a unique identifier of the scenario execution.

# 2. Execute a scenario
Write-Host "Running Suite " $suiteId
$uri = "http://{0}:{1}/QuerySurge/api/project/{2}/execute/suite?id={3}&name={4}&inherit=false&appendtime=false" -f $hostname, $port, $projectId, $suiteId, $scenarioName
$execution = Invoke-RestMethod -Uri $uri -Method Post -Headers @{ "accept" = "application/json"; "X-QS-AUTH" = $sessionId } -ContentType "application/json"
Write-Host $execution.guid

REST API: Execute Scenario

Lastly we need to issue a Logout call to log the user out and expire the $sessionId.

# 3. Logout
$uri = "http://{0}:{1}/QuerySurge/api/auth/logout" -f $hostname, $port
$logout = Invoke-RestMethod -Uri $logoutURI `-Method Post ` -Headers $logoutHeaders ` -ContentType "application/json"

Write-Host "Done!"

REST API: Logout

 

Linux CLI:

We will now examine the same example use case within a Linux environment. Following is a typical script needed to execute a scenario via the CLI in a Linux environment.

## ' ********************* START OF CONFIGURATION VARIABLES ************************
cliPath="###ROOT_DIR###/cli/qscli.sh"
host='127.0.0.1'
port=80
username='admin'
password='admin'
projectId='1'
suiteId="1"
## ' ********************* END OF CONFIGURATION VARIABLES ************************

echo "Running Suite $suiteId..."
scenarioId=`$cliPath runTestSuiteById "--hostname $host--port $port --username $username --password $password --projectId $projectId" $suiteId`
echo "The scenario $scenarioId has started"


echo "Done!"

CLI: Sample Script (Linux)

 

Linux REST API:

For REST API calls in a Linux environment, the parameters remain the same as with Windows. We use the curl utility to perform the HTTP requests instead. As with the Windows example, the process begins with an authentication call to obtain a session ID, which is required for all subsequent API calls.

We then call the REST API endpoint to start a scenario execution in QuerySurge and obtain the execution guid.

Finally a logout request is made to properly terminate the session.

These steps are described in the code sample below.

## ' ********************* START OF CONFIGURATION VARIABLES ************************
username="admin"
password="admin"
hostname="127.0.0.1"
port=80
projectId=1
scenarioName="MyScenario"
suiteId="1"
## ' ********************* END OF CONFIGURATION VARIABLES ************************

# 1. Login
response=$(curl -s -X POST "http://$hostname:$port/QuerySurge/api/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"username\":\"$username\",\"password\":\"$password\",\"globalLogin\":false}")
sessionId=$(jq -r '.sessionId' <<< "${response}")

# 2. Execute a Scenario
echo "Running Suite $suiteId..."
response=$(curl -s -X POST "http://$hostname:$port/QuerySurge/api/project/$projectId/execute/suite?id=suiteId&name=$ScenarioName" -H "accept: application/json" -H "X-QS-AUTH: $sessionId" -H "Content-Type: application/json") 
scenarioExecutionGUID=$(jq -r '.guid' <<< "${response}")
echo "Scenario executionId: $scenarioExecutionGUID"

# 3. Logout
echo "Logging out"
$(curl -s -X POST "http://$hostname:$port/QuerySurge/api/auth/logout" -H "accept: */*" -H "X-QS-AUTH: ${sessionId}" )
echo "--- end --------------------------------"

REST API: Sample Script (Linux)

 

Note the optional use of jq - a powerful external Linux utility which helps in json parsing.

 

Related articles