V-Spark Online Help

Using the /status API with Python

V‑Spark's /status API is a read-only API that provides programmatic access to status information about various levels of the hierarchy of a V‑Spark installation. As explained in Reference for the /status API and shown in the examples in Using the /status API with cURL, the API enables you to pass the level of the hierarchy that you are interested in as part of the URL of the /status call, and specify the format in which you want the output data to be returned as the format parameter to the call.

To read data from a V‑Spark installation, you can use the root token, but that's analogous to running every Linux command as the superuser. It is cleaner to use the authorization token that is associated with each company. You only need the root token when reading multi-company information, such as when retrieving the root token for each company in the V‑Spark installation.

As shown previously in Integrating Multiple GET Results Using Python, you can dynamically retrieve company information from a V‑Spark installation (in the gettokens() function) and folder information for the organizations in that company (retrieved in the getfolderinfo() function). You can then combine the company and token information with the folder information in order to explore all of the companies, organizations, and folders in a V‑Spark installation (in the printfolders() function).

The sample code on this page builds on the code from the previously linked example in several ways:

  • Sharing the gettokens() and getfolderinfo() functions shows that extracting company and token information and establishing the relationship between company token information and the hierarchical aspects of companies, organizations, and folders are common tasks when writing many V‑Spark applications.

  • Replacing the printfolderinfo() function with a findfolders() function makes it easy to call another function to interact with each folder.

  • Adds a writefolderstatus() function to perform the key functionality of the example, writing status information for that level of their hierarchy in the format that you specified on the command line.

The following code walkthrough highlights how this example works.

Figure 1. Sample Python Code to Retrieve /status Information
#!/usr/bin/env python
# Copyright 2017 Voci Technologies  All rights reserved.
# Contains confidential company information.
# Unsupported example code - Not for production use.
# Application that reads company and folder information about a
# product installation on a specified host, then uses the company's
# short name to link the two. The application then uses the company's
# short name, the organization's short name, and each folder name to
# call the /status API for each folder. The output format (json or
# csv) is specified as the third argument, and determines both the
# extension of the files that are written to and the format of their
# content.

import requests
import json

def usage(argv):
    print "Usage:", argv[0], "<sparkhost:port> <root token> <csv || json>"

def main(argv): 1
    if len(argv) != 4: usage(argv) 2
    host, token, output_format = argv[1:]
    tokens = gettokens(host,token)
    folderinfo = getfolderinfo(host,token)
    getfolders(host, folderinfo, tokens, output_format)

def gettokens(host, token): 3
    url = "http://%s/config?token=%s" % (host,token)
    cfg = requests.get(url).json()
    return dict([(comp,d['uuid']) for comp,d in cfg.iteritems()])

def getfolderinfo(host, token): 4
    url = "http://%s/config/folders?token=%s" % (host,token)
    return requests.get(url).json()

def findfolders(host, folder_info, tokens, output_format): 5
    for comp, comp_data in folder_info.iteritems():
        print comp+" (Token: "+tokens[comp]+")"
        for org, org_data in comp_data.iteritems():
            for folder, folder_data in org_data.iteritems():
                writefolderstatus(host, tokens[comp], comp, org, folder, output_format)

def writefolderstatus(host, token, comp, org, folder, output_format):  6
    url = "http://%s/status/%s/%s/%s?token=%s&format=%s" % (host, comp, org, folder, token, output_format)
    print "  URL is "+url
    OUTPUT_FILE = comp+"-"+org+"-"+folder+"-status."+output_format
    print "    Writing JSON to "+OUTPUT_FILE
    target = open(OUTPUT_FILE, 'w')
    if output_format == "json":
        target.write(json.dumps(requests.get(url).json(), indent=4, sort_keys=True))
    if output_format == "csv":
        response = requests.get(url)

if __name__ == '__main__': 7
    from sys import argv

The major steps in the Python application shown in this sample code are the following:


The main function provides a traditional main routine that shows the order in which functions are called in the application


Check if the right number of command-line arguments have been provided. Assign them to appropriate variables if so, and identify the expected arguments if not.


Uses the /config API to retrieve the company information from the V‑Spark installation and build a dictionary that only contains the company name and associated token information from the host that was specified on the command line


Uses the /config/folders API to retrieve the folder-level configuration information from the host that was specified on the command line


Initiates the primary loop for the application, which is controlled by the companies that were found in the information that was retrieved from the host specified on the command line. Each company has an associated authorization token (originally stored in the uuid name/value pair), which is the other field for each company entry in the dictionary that was constructed in the gettokens()function. The short name for each company is the data item in the company JSON that provides the linkage between the data from the company and folder sources. This loop then uses this information to walk the company/organization/folder hierarchy in the V‑Spark installation that was specified on the command line, calling the function that represents the core functionality of this application.


Writes status information in the format that was requested on the command line to a file whose name is CO_SHORT-ORG_SHORT-FOLDER-status.output-format.


The name of the scope in which the top-level code executes. This enables the sample application to execute standalone or as a part of another application. This is a standard Python notation, and is not anything that is specific to V‑Spark.