How to use the RestAPI with Python

Owned by Former user (Deleted)
Last updated: Nov 06, 2018

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 Python to produce a CSV file 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.

Other documents in the Knowlede Base showing how to produce equivalent results have been written for PHP 7 (which produces HTML output), PERL and for PowerShell

A longer worked example in python can be found here.

Pre-requsites

  • NOTE: both Python 2 and Python 3 are actively used in different environments. This example uses Python 3 syntax.
  • You need to know the URL for you iQSonar install - in this example our host is iqsonar-host
  • You need credentials for the iQSonar install - in this example we use the default login admin / password Please update this to the correct values for your site.
  • You need the  "requests" module for Python which handles web requests very nicely. If this is not installed on your system you can install it as follows:

On Linux or macOS:

pip install -U pip requests

On Windows:

python -m pip install -U pip requests

Step One - Connect to the host

The RestAPI uses HTML basic authentication - for this example we will use the default user name of admin and a password of password. In a production environment you should always change the default credentials.

The requests module handles the HTTP details for us.

Connect to host
import requests

r = requests.get('http://iqsonar-host/api/v1/devices',auth=('admin','password'))
max = r.headers['X-fetch-count']
data = r.json()
count = len(data)

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. The variable max contains the total number of devices. If this is more than 200 we would need to fetch a second batch - see other worked examples in this series for more details on that. In this example we will print at most 200. data holds the RestAPI data converted into a Python data structure, count is the number of devices returned. Also note that if you specify incorrect credentials, Python will throw an exception when you call the r.headers method.

At this point in the script, we have a variable data which contains the JSON output from the Rest API. 

The data structure is a JSON array of objects, each object contains an array of device attributes:

  • device_id
  • host_name
  • serial_number
  • manufacturer
  • model
  • last_scan
  • self

The “self” attribute is particularly interesting, as it is a URL that gives the link to more details about the device. Also note that if the device in question does not have a value, the key is omitted.

(Note that by default the REST API returns a list of 200 devices at a time. Use the off_set and fetch_size parameters to page through a longer list of devices.

Step Two - print out Hostname, RAM and CPU details for each device

Find the hostname
i = 0
print ('Host,RAM,CPU Type')
while (i < count):
  row = data[i]
  if ( 'host_name' in row ):
    hostname = row['host_name']
  else:
    hostname = '(no hostname)'

The JSON to Python converter does not create empty key-value pairs for missing data, so we need to test for the key's existence each time when we're using it in a script (hence all the if..else statements)

For each device, we get the host_name (which can be empty) and the self (which is always set) values.  'self' contains a URL pointing to detailed information on the device which we then fetch to get the RAM and CPU information.

Find the rest of the details
  url2 = row['self']
  r2 = requests.get(url2,auth=('admin','password'))
  device = r2.json()
  if ('total_memory_mb' in device):
    ram = device['total_memory_mb']
  else:
    ram = '(unknown ram)'

  if ('cpu' in device):    
    cpu = device['cpu'][0]['cpu_model']
    cpu = cpu.replace(',','')
  else:
    cpu = '(unknown cpu)'  
  print (hostname,',',ram,',',cpu,sep='')
  i+=1


The CPU information if present is an array. In almost all architectures CPUs in a multi-cpu motherboard are identical, so for the putposes of this example, we just save the results for the first CPU.
We then print off the hostname, ram and cpu info seperated by commas. We strip any commas from the cpu name to keep our CSV file valid.

 Completed Code

Completed Script
#
# RestAPI duplicate the PowerShell example in Python
#
import requests
# Set this to your own host name/login/password)
r = requests.get('http://iqsonar-host/api/v1/devices',auth=('admin','password'))
max = r.headers['X-fetch-count']
data = r.json()
count = len(data)
i = 0
print ('Host,RAM,CPU Type')
while (i < count):
  row = data[i]
  if ( 'host_name' in row ):
    hostname = row['host_name']
  else:
    hostname = '(no hostname)'
  url2 = row['self']
  r2 = requests.get(url2,auth=('admin','password'))
  device = r2.json()
  if ('total_memory_mb' in device):
    ram = device['total_memory_mb']
  else:
    ram = '(unknown ram)'
  if ('cpu' in device):    
    cpu = device['cpu'][0]['cpu_model']
    # remove commas from the cpu string so as to keep the CSV output valid
    cpu = cpu.replace(',','')
  else:
    cpu = '(unknown cpu)'  
  print (hostname,',',ram,',',cpu,sep='')
  i+=1