The REST API allows users to query the iQSonar results directly using the web client protocol. The results are returned in JSON format. This article is part of a series on how to make use of the Rest API.

This worked example uses PHP to produce results in HTML to display in a web browser, containing details of devices directly from the scan results. We look for the host name, the total installed RAM and the CPU type. The device name will be listed in the "device" results. For the CPU Type and the installed RAM we need to then go to the details page for the device.

This article is one in a series showing how to use the REST API to produce sample output. Other examples producing equivalent results in CSV format have been written for Python, PERL and for PowerShell

Pre-requisites

The script is written in PHP 7. It should work with any web server that supports PHP 7 (e.g. Apache, IIS, Nginx)
The script relies on two optional modules php7-curl for web requests and php7-json
You need to know the url for your iQSonar instance
You need to know the basic authentication credentials for your iQSonar instance

Step One - build the CURL connection to the Rest API host

As before, use your local values for the host name, username and password for the Rest API host.

Connect to the remote host

// update these for your location
$rhost = "iqsonar-host";
$aname = "admin";
$psswd = "password";

/* 
 * Use curl to fetch the results from the REST API
 */
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_VERBOSE, 0);		// setting the verbose flag to 1 sends all CURL output to stderr. Don't want this.
curl_setopt($ch, CURLOPT_HEADER, 1);		// we need info from the header
curl_setopt($ch, CURLOPT_USERPWD, $aname . ":" . $psswd);

curl_setopt($ch, CURLOPT_URL, "http://" .$rhost ."/API/v1/applications?fetch_size=1");

$response = curl_exec($ch);

// We want to parse the headers to find X-fetch-count
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $header_size);

// explode multiline response headers into an array of lines
$header = explode("\n",$headers);
foreach ($header as $line)
{
	// find the two headers we're specifically interested in
	list($key,$value) = explode(": ",$line);
	if (strcasecmp($key,"X-fetch-count")==0) { $max = $value; }	// total no of devices in database
	if (strcasecmp($key,"X-fetch-current-size")==0) { $count = $value; }// count of devices returned in THIS query - will stop at 200 if there are more than 200 results
}

$body = substr($response, $header_size);
$jsondata = json_decode($body, true); // recursive associative array please

By default the REST API "/api/v1/devices" page will return 200 devices at a time. We can increase or decrease this using the "fetch_size" parameter in the URL. The X-fetch-count header contains the total number of devices in the dataset. The X-fetch-current-size header shows how many were returned in this batch of results.

The body of the result is coded in JSON. The php function json_decode will convert JSON into a PHP variable. Passing "True" as the second parameter means return the data as an associative array.

Step through the results

As a simple example, we're going to produce a HTML Table containing hostname, ram and CPU for each scanned device. The summary info returned in the first API call above contains the hostname and a link to the rest of the device details.
At this point we also prepare the start of the output.

Find hostname and link

$output = "<html><head><title>List of Devices</title></head>\n<body>\n";
$output = "<p>Details for " . $count . " devices.</p>\n";

$output .= "<table border='1' cellpadding='1'>\n<tr><td>Hostname</td><td>RAM</td><td>CPU</td></tr>\n";
echo "$output";

$ch2 = curl_init();											// move this out of the loop later
curl_setopt($ch2, CURLOPT_USERPWD, $aname . ":" . $psswd);	// move this out of the loop later
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch2, CURLOPT_VERBOSE, 1);
curl_setopt($ch2, CURLOPT_HEADER, 1);
$output = "";

$i=0;
while ($i != $count)
{
	
	$hostname = $jsondata[$i]["host_name"] ?? "(no hostname)";
	$self = $jsondata[$i]["self"];

	// do something

	$i++;
}

With the $self url we need to do a second api call to get the remaining details and parse the resulting JSON. Therefore our "do something" expands out as follows:

	curl_setopt($ch2, CURLOPT_URL, $self);						
	$device_response = curl_exec($ch2);	
	$header_size = curl_getinfo($ch2, CURLINFO_HEADER_SIZE);
	$devicedetails =  substr($device_response, $header_size);

	$device = json_decode($devicedetails,true);
	$ram = $device['total_memory_mb'] ?? "(no ram info)";
	$cpu = $device['cpu'][0]['cpu_model'] ?? "(no cpu info)" ;
	$output .= "<tr><td>$hostname</td><td>$ram</td><td>$cpu</tr>\n";
	
	curl_close($ch2);

We call curl_close() to free up memory as we go through the loop - lets not crash the web server.

Completed Code

Completed Script

<?php
// PHP script to use REST API to get a list of devices from a project and return it as a table
/*
 * PHP7.1 used
 * Additional Extensions used (may need to be installed separately):
 * - curl
 * - json
 */
 
// update these for your location
$rhost = "iqsonar-host";
$aname = "admin";
$psswd = "password";

/* 
 * Use curl to fetch the results from the REST API
 */
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $aname . ":" . $psswd);

curl_setopt($ch, CURLOPT_URL, "http://" .$rhost ."/API/v1/devices");

$response = curl_exec($ch);

// We want to parse the headers to find X-fetch-count
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $header_size);

// explode multiline response headers into an array of lines
$header = explode("\n",$headers);
foreach ($header as $line)
{
	// find the two headers we're specifically interested in
	list($key,$value) = explode(": ",$line);
	if (strcasecmp($key,"X-fetch-count")==0) { $max = $value; }	// total no of devices in database
	if (strcasecmp($key,"X-fetch-current-size")==0) { $count = $value; }// count of devices returned in THIS query
}


$body = substr($response, $header_size);
$jsondata = json_decode($body, true); // recursive associative array please

$output = "<html><head><title>List of Devices</title></head>\n<body>\n";
$output = "<p>Details for " . $count . " devices.</p>\n";

$output .= "<table border='1' cellpadding='1'>\n<tr><td>Hostname</td><td>RAM</td><td>CPU</td></tr>\n";
echo "$output";

$ch2 = curl_init();											
curl_setopt($ch2, CURLOPT_USERPWD, $aname . ":" . $psswd);	
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch2, CURLOPT_VERBOSE, 1);
curl_setopt($ch2, CURLOPT_HEADER, 1);
$output = "";

$i=0;
while ($i != $count)
{
	
	$hostname = $jsondata[$i]["host_name"] ?? "(no hostname)";
	$self = $jsondata[$i]["self"];
	curl_setopt($ch2, CURLOPT_URL, $self);						
	$device_response = curl_exec($ch2);	
	$header_size = curl_getinfo($ch2, CURLINFO_HEADER_SIZE);
	$devicedetails =  substr($device_response, $header_size);

	$device = json_decode($devicedetails,true);
	$ram = $device['total_memory_mb'] ?? "(no ram info)";
	$cpu = $device['cpu'][0]['cpu_model'] ?? "(no cpu info)" ;
	$output .= "<tr><td>$hostname</td><td>$ram</td><td>$cpu</tr>\n";
	
	curl_close($ch2);
	$i++;
}
$output .= "</table>\n</body>";

echo $output;

?>

Page:

RestAPI OutputDevices
Page:

Configure target locations using the RestAPI
Page:

Clear down your site config via the RestAPI
Page:

Use REST API and Powershell to get list of scanned databases
Page:

How to use the RestAPI with Python

Pre-requisites

Step One - build the CURL connection to the Rest API host

Step through the results

Completed Code

Related articles

Browser not supported