Example Application: REST 101

A very simple REST application that interfaces to Accelerator’s REST API is as follows. It reads and reports the NC queue name for the given URL.

 1 #!/usr/bin/python 
 2 # 
 3 # nc_rest_101.py 
 4 # 
 5 import os, sys, string, requests, json 
 6 from getToken import getJWT, getMyPassword 
 7 
 8 url= os.environ['NC_URL'] 
 9 jwt = getJWT( url, os.environ['USER'], getMyPassword()) 
10 query = url + '/api/v3/project/1/project' 
11 r = requests.get(query, headers={'Authorization': jwt}) 
12 print ( json.dumps(r.json(),indent=2))

Some explanation about the simple program:

Line 6 imports the getToken.py module. See getToken.py source code in a later section of this tutorial.
Line 9 requests the access token, a JWT, from the server. This token identifies the current user and authenticates and authorizes REST requests until the token expires.
Line 10 shows how to assemble the right URL for the query from the REST API name space.
Line 11 shows how to generate the correct HTTP GET request that transmits the REST API request.
Line 12 pretty-prints the JSON response returned from the server.

Before you run this program or other examples that call getJWT(), create the getToken.py module in the same directory using the source code found in the “JWT Token Allocation” section later in this tutorial.

Run this program as follows:

% echo $NC_QUEUE 
MY_NC_QUEUE 
% export NC_URL="`nc cmd vovbrowser`" 
% echo $NC_URL 
http://ncserverhost.domain.myco.com:10574 
% python nc_rest_101.py 
Password: 
{ 
    "rows": [ 
        [ 
            "MY_NC_QUEUE" 
        ] 
    ], 
    "errormsg": "", 
    "startrow": 1, 
    "query": "SELECT project FROM 1", 
    "columns": [ 
        { 
            "field": "PROJECT", 
            "col": 0 
        } 
     ], 
     "endrow": 1 
}

Example Applications: Job Submit and List

To prove 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.

% 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    kfeind1  vw sleep 33 > JOBLOG.1411 
000045083    Running       normal    kfeind1  vw sleep 66 > JOBLOG.1925

nc_run.py

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

import os, sys, random, string, pwd, json, requests, grp 
from getToken import getJWT, getMyPassword 

def runJob(url, jwt, jobCommand ): 
    resturl = url + "/api/v3/jobs" 
    VOV_JOB_DESC = { 
        "command" : jobCommand, 
        "logfile" : "JOBLOG." + str(random.randint(1000,2000)), 
        "rundir" : os.getcwd(), 
        "env" : "BASE", 
    } 
    r = requests.post(resturl, json=VOV_JOB_DESC, 
                      headers={"Authorization": jwt}) 
    if ( r.status_code < 300 ): 
        print ("New job is %s" % r.json()["jobid"]) 
        return 0 
    else: 
        print ("Error code: %d" % r.status_code) 
        print ("Error message: %s" % r.json()["errormsg"]) 
        return 1 

# 
# 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::]) 

jwt = getJWT( url, os.environ["USER"], getMyPassword()) 
stat = runJob(url, jwt, command) 
exit(stat)

nc_list.py

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

import os,sys,random,string 
import pwd 
import json 
import requests 
from getToken import getJWT 
from getToken import getMyPassword 

def listJob(url, jwt): 
    query = ( url + '/api/v3/query' 
              + '?select=id,statusnc,PRIORITYPP,host,command' 
              + '&from=System:User:' + os.environ['USER'] ) 
    r = requests.get(query, headers={'Authorization': jwt}) 
    if ( r.status_code >= 300 ): 
        print ("Error: status %d received" % r.status_code ) 
        exit(1) 
    return r.text 

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) 
jwt = getJWT( url, os.environ['USER'], getMyPassword()) 

json_text = listJob(url, jwt) 
prettyPrint(json_text)