WebMO Help - REST-JSON Interface (Enterprise)

Preqresites

WebMO's REST implementation requires the following:

  1. The webserver must support PUT, PATCH, and DELETE methods. For the Apache webserver, modify userdir.conf to add these as follows:
    <Directory "/home/*/public_html">
    AllowOverride FileInfo AuthConfig Limit
    Options MultiViews SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS PUT DELETE PATCH
    </Directory>
  2. The perl that is installed on the system must support CGI-Application, JSON, Exception-Class, Try-Tiny, Switch, and CGI-Application-Dispatch. These are often installed by default on newer systems, but frequently must be added to older systems. Thus, these perl modules are distributed with WebMO in <cgiBase>/lib, but system versions will be used if available.

REST Access to WebMO

WebMO Enterprise supports querying of WebMO though a REST (Representational State Transfer) interface. REST allows a user or administrator to submit queries and obtain data via HTTP(S) using specially crafted URL's. The REST response is a set of text characters, which could be data, the contents of a file, or the result of a program.

For example, parsed calculation results that typically appears on the Job Results page can also be accessed via a URL request by users. Job, folder, user, and group information can be queried by administrators. Some administrative actions, such as renaming or deleting jobs, can also be carried out using REST.

A REST query consist of several components:

For example, a REST query could look like:
http://server.university.edu/cgi-bin/rest/students?class=seniors
where the method is GET (implied by the ?), the root is server.university.edu/cgi-bin/rest/, the path is students, and the query is class=seniors. The returned data from this URL would presumably be a list of senior students at the university.

A table of REST queries supported by WebMO follows. The following actions are defined in <cgiBase>/rest.cgi. Examples of their usage are provided in <cgiBase>/REST/templates and in WebMO.install/REST_examples/comprehensive.py.

Path Method Query / Data Description
jobs GET If requesting as an administrative user {user : smith}; Can optionally filter with {folderID, engine, status, jobname} Request an enumeration of all jobs for the current user
jobs/<jobNumber> PATCH Specify information to be changed {folderID, jobname} Modify a job
jobs/<jobNumber> DELETE Delete a job
jobs POST Specify local file {outputFile} and parameters {jobname, engine} Import a job from an existing local output file (regular users only)
jobs/<jobNumber>/[|results|geometry|raw_output|archive] GET Request information about a specific job
folders GET If requesting as an administrative user, {user: smith} Enumerate all folders for the current user
users GET Enumerate all WebMO users on the system, or in the group if a sub-admin (administrative users only)
users/<username> GET Request information on a specific user
groups GET Enumerate all WebMO groups on the system (administrative users only)
groups/<groupname> GET Request information on a specific group, including enumeration of group members (administrative users only)
sessions POST {'username' : smith, 'password' : secret} Obtain session token
sessions DELETE Delete session token
templates/rest/<templateName> GET authentication not required Load Python program in REST/templates directory, with $jobNumber and $username variable substitution
status GET authentication not required Status of webmo server

JSON Format of Returned Data

WebMO returns REST data queries in JSON (JavaScript Object Notation) format, which is a language-independent format of attribute-value pairs.

As an example, a geometry optimization job for water could result in the following response:

{"success":true,"molecular_multiplicity":1,"connectivity":[[1,2,1],[1,3,1]],"provenance":{"creator":"Gaussian"},"molecular_charge":0,"schema_name":"QC_JSON","properties":{"rhf_energy":{"value":-76.0107465155,"units":"Hartree"},"rotational_constants":[858.6603475,440.9401844,291.3340235],"route":" #N HF/6-31G(d) OPT Geom=Connectivity","scf_dipole_moment":[0,0,2.1989],"symmetry":"C2V","dipole_moment":[0,0,2.1989],"cpu_time":{"value":6.1,"units":"sec"},"stoichiometry":"H2O","basis":"6-31G(d)"},"comment":"H2O; Geometry Optimization","symbols":["O","H","H"],"geometry":[0,0,0.114681,0,0.754069,-0.458726,0,-0.754069,-0.458726],"schema_version":0}

which is more easily understood when formatted as:

{
   "success": true,
   "molecular_multiplicity": 1,
   "connectivity": [[1,2,1],[1,3,1]],
   "provenance": {
      "creator": "Gaussian"
   },
   "molecular_charge": 0,
   "schema_name": "QC_JSON",
   "properties": {
   "rhf_energy": {
      "value": -76.01075,
      "units": "Hartree"
   },
   "rotational_constants": [858.66034,440.9402,291.334],
   "route": " #N HF/6-31G(d) OPT Geom=Connectivity",
   "scf_dipole_moment": [0,0,2.1989],
   "symmetry": "C2V",
   "dipole_moment": [0,0,2.1989],
   "cpu_time": {
      "value": 6.1,
      "units": "sec"
   },
   "stoichiometry": "H<sub>2<\/sub>O",
   "basis": "6-31G(d)"
   },
   "comment": "H2O; Geometry Optimization",
   "symbols": ["O","H","H"],
   "geometry": [0,0,0.114681,0,0.754069,-0.458726,0,-0.754069,-0.458726],
   "schema_version": 0
}

Most computer languages have libraries for reading JSON data, extracting values based on attribute, and assigning values to variables for use in subsequent calculations.

JSON formatted result data can also be directly downloaded from the Job Manager by selecting jobs and then choosing Download: JSON.

Issuing WebMO REST Requests from the Command Line

Curl (Client URL) is a command-line tool for transferring data using various protocols. REST queries can be issed manually from the command line with the curl utility. For example:

$ curl http://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi/status

returns

{"url_cgi":"http://server.university.edu/~webmo/cgi-bin/webmo","jobs":302,"timestamp":"1/10/20 16:09","version":".0.002e"}

which gives the URL, total number of jobs run, time of last job, and version of the WebMO instance.

Job information is typically password protected. The following curl commands illustrate the creation of a token with a POST, use of the token to obtain user information and job information with GET's, and deletion of the token with a DELETE.

$ curl https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi/sessions -d "username=smith&password=secret"
{"token":"PIcjs8PXGAw","username":"smith"}

$ curl https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi/users/smith?token=PIcjs8PXGAw\&username=smith
{"admin":false,"user":"smith","properties":{"archiveFormat":"tar","fullName":"John Smith","allowNewUsers":"1","enabledQueues":"all","jobTimeLimit":"-1","timeLimit":"-1","email":"smith@university.edu","viewJobInNewWindow":"0","enabledInterfaces":"all","emailNotification":"0","enabledServers":"all"}}

$ curl https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi/jobs/2/results?token=PIcjs8PXGAw\&username=smith
{"success":true,"molecular_multiplicity":1,"connectivity":[[1,2,1],[1,3,1]],"provenance":{"creator":"Gaussian"},"molecular_charge":0,"schema_name":"QC_JSON","properties":{"rhf_energy":{"value":-76.0107465155,"units":"Hartree"},"rotational_constants":[858.6603475,440.9401844,291.3340235],"route":" #N HF/6-31G(d) OPT Geom=Connectivity","scf_dipole_moment":[0,0,2.1989],"symmetry":"C2V","dipole_moment":[0,0,2.1989],"cpu_time":{"value":6.1,"units":"sec"},"stoichiometry":"H<sub>2</sub>O","basis":"6-31G(d)"},"comment":"H2O; Geometry Optimization","symbols":["O","H","H"],"geometry":[0,0,0.114681,0,0.754069,-0.458726,0,-0.754069,-0.458726],"schema_version":0}

$ curl -X DELETE https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi/sessions?token=PIcjs8PXGAw\&username=smith
{"results":"success"}

Issuing WebMO REST requests from using Python

The real power of REST queries is that information can be accessed from within a program, such as Python.

Python needs to be available to the local user. Python is typically installed by default on Linux systems. On Mac OS X, one can either install Python 3 using Jupyter (see below) or perform a "sudo pip install requests" on the existing Python 2.7 installation. On Windows, one must install Python, which is must easily done using Jupyter (see below).

The following Python program is similar to the above curl commands. It obtains an authorization token, uses of the token to obtain the user email and calculation energy, and deletes the token.

#minimal.py
#create authorization token
import requests
from getpass import getpass
baseURL = "https://server.university.edu/~webmo/cgi-bin/webmo/rest.cgi"
username=input('Enter WebMO username:')
print("Enter WebMO password:")
password=getpass()
login={'username' : username, 'password' : password}
r = requests.post(baseURL + "/sessions", data=login)
auth=r.json()
#REST request for information about user
r = requests.get(baseURL + "/users/%s" % username, params=auth)
results=r.json()["properties"]["email"]
print(results)
#REST request for information about job
jobNumber=int(input('Enter WebMO job number:'))
r = requests.get(baseURL + "/jobs/%d/results" % jobNumber, params=auth)
results=r.json()["properties"]["rhf_energy"]
print(results)
#delete authorization token
r = requests.delete(baseURL + "/sessions", params=auth)

Running this Python program on the local computer results in the following output:

$ python minimal.py
Enter WebMO username:smith
Enter WebMO password:
Password: <secret>
smith@university.edu
Enter WebMO job number:2
{'value': -76.0107465155, 'units': 'Hartree'}

Additional examples of REST programs are provided in the <cgiBase>/REST/templates directory:

and in the WebMO.install/REST_examples directory: