Example Application: REST 101

Programs that use the Accelerator REST API can do so in two ways. The preferred approach is to utilize the Python library module "vov_rest_v3", which is provided with Accelerator software packages in the file vov_rest_v3.py. This Python module simplifies coding by hiding details of the HTTP operations that interface directly to the low level REST API. The vov_rest_v3 module requires Python version 3 or higher.

For more advanced users, a later section of this guide shows how to interface directly to the REST API. Direct use can give you more control over the following:

Management of JWT access tokens
Policy of your application regarding insecure HTTPS configurations
Control over the use of connection "keep-alive"

Direct REST API interface will be covered later. This approach works with Python version 1 and higher.

To get a quick start using REST, examine a simple "REST 101" example Python program that queries REST to return the name of an NC queue, shown below. The lines of the program are numbered and annotated with explanations.

 1   #!/usr/bin/python3
    2   #
    3   # nc_rest_101.py
    4   #
    5   import os, sys, getpass, json
    6   import vov_rest_v3
    7
    8   url = os.environ['NC_URL']
    9
   10   vrest = vov_rest_v3.VOVRestV3()
   11   vrest.authorize(url, getpass.getpass('Password:') )
   12   r = vrest.submitRequest("GET", url + "/api/v3/project/1/project")
   13
   14   print ( json.dumps(json.loads(r), indent=2) )

Here is a line-by-line guide to the above program.

Line 1: This Python program is compatible with Python 3.
Line 6: Import the vov_rest_v3 Python module that comes with the Accelerator product. Copy it locally from $VOVDIR before running the Python program.
Line 8: Pull the URL for the NC queue out of an environment variable. The URL is what nc cmd vovbrowser shows.
Line 10: Allocate vrest, an instantiation of the VOVRestV3 Python class.
Line 11: The authorize() method function authenticates using the password and allocates a JWT token stored in the object. This example obtains your user password by interactive prompt.
Note: This example uses username/password authentication. To use key-based authentication, see .
Line 12: The HTTP get request is sent, returning a string containing the HTTP response data in JSON format.
Line 14: The HTTP response string is parsed into JSON and pretty-printed.

Here is a terminal session that shows how to run the program.

% echo $NC_QUEUE
My_NC_QUEUE
% export NC_URL=`nc cmd vovbrowser`
% echo $NC_URL
http://myhost:6330
% cp $VOVDIR/scripts/python/vov_rest_v3.py .
% python3 nc_rest_101.py
Password:
{
  "startrow": 1,
  "endrow": 1,
  "query": "SELECT project FROM 1",
  "errormsg": "",
  "columns": [
    {
      "col": 0,
      "field": "project"
    }
  ],
  "rows": [
    [
      "My_NC_QUEUE"
    ]
  ]
}

Example Applications: Job Submit and List

To demonstrate the utility of the REST API, here are two simple Python programs that imitate the function of the nc run and nc list commands that are familiar CLI tools from the Accelerator product. The source code for these tools, named nc_run.py and nc_list.py, is found on the following pages.

These REST programs only require that the NC_URL environment variable be set to the Accelerator queue URL, as returned by nc cmd vovbrowser. Here is a terminal image that demonstrates the simple REST tools.

% cp $VOVDIR/scripts/python/vov_rest_v3.py .
% export NC_URL="`nc cmd vovbrowser`" 
% ./nc_run.py sleep 33 
Password: 
New job is 45080 
% ./nc_run.py sleep 66 
Password: 
New job is 45083 
% ./nc_list.py 
Password: 

       ID   STATUSNC    PRIORITYP       HOST        COMMAND 
000045080    Running       normal    myhost   vw sleep 33 > JOBLOG.185633
000045083    Running       normal    myhost   vw sleep 66 > JOBLOG.903723

nc_run.py

#!/usr/bin/python3 
# 
# nc_run.py 
# 
# Usage 
# 
#     export NC_URL=<URL FOR NC QUEUE> 
#     ./nc_run.py <command> [args] 
# 

import os, sys, random, json, getpass 
import vov_rest_v3 

def getMyPassword(): 
    return getpass.getpass('Password:') 

# Main body 
nc_url = os.environ["NC_URL"] 
scheme = nc_url.split(":")[0] 
hostport = nc_url.split("/")[2] 
url = "{0}://{1}".format(scheme, hostport) 
command = " ".join(sys.argv[1::]) 

vrest = vov_rest_v3.VOVRestV3() 
vrest.authorize(url, getMyPassword()) 

# Job attributes - required 
VOV_JOB_DESC = { 
    "command" : command, 
    "logfile" : "JOBLOG." + str(random.randint(100000,999999)),
    "rundir" : os.getcwd(), 
    "env" : "BASE", 
} 

# Job attributes - optional / User specified 
VOV_JOB_DESC.update( { 
    "priority,sched" : 4, 
} ) 
r = vrest.submitRequest("POST", url + "/api/v3/jobs", jsonData=VOV_JOB_DESC) 
print ("New job is %s" % json.loads(r)["jobid"])

nc_list.py

#!/usr/bin/python3
# 
# nc_list.py 
# 
# Usage 
# 
#       export NC_URL=<URL FOR NC QUEUE> 
#       ./nc_list.py 
# 

import os, sys, json, getpass
import vov_rest_v3

def getMyPassword():
    return getpass.getpass('Password:')

def listJob(vr, url):
    query = ( url + '/api/v3/query' 
              + '?select=id,statusnc,PRIORITYPP,host,command' 
              + '&from=System:User:' + os.environ['USER'] ) 
    response = vr.submitRequest("GET", query)
    return response

def prettyPrint( text ): 
    dd = json.loads(text) 
    for ii in range(0, len(dd['columns']) ) : 
        sys.stdout.write("%9.9s " % dd['columns'][ii]['field']) 
    sys.stdout.write("\n") 
    if ('rows' not in dd): 
        return 
    for rr in range (0, len(dd['rows']) ) : 
        row = dd['rows'][rr] 
        for ii in range(0, len(dd['columns']) ) : 
            if (ii < len(dd['columns'])-1): 
                sys.stdout.write("%9.9s " % str(row[ii])) 
            else: 
                sys.stdout.write("%10.30s" % str(row[ii])) 
        sys.stdout.write("\n") 

# 
# Main body 
# 
nc_url = os.environ['NC_URL'] 
scheme = nc_url.split(":")[0] 
hostport = nc_url.split("/")[2] 
url = "{0}://{1}".format(scheme, hostport) 

vrest = vov_rest_v3.VOVRestV3()
vrest.authorize(url, getMyPassword())
json_text = listJob(vrest, url)
prettyPrint(json_text)