Obtain and Use the REST API Utility Classes

This page is maintained for posterity, but customers are encouraged to visit the GitHub repository for all subsequent updates to the library (including changelogs). Unless otherwise specified, changes are only made in the Python version of the library.

Changelog

Dec. 19, 2017:

• glsapiutil v3 ALPHA (bleeding-edge library) released on GitHub. GitHub has the most current library.

• Links to library removed from this page.

Dec. 15, 2016:

• reportScriptStatus() function had a bug that caused it to not work when a <message> node was unavailable. This has been fixed.

• deleteObject() functions now available for both v1 and v2 of the library.

• getBaseURI() should now return a trailing slash at the end of the URI string.

• getFiles() function added to batch retrieve files.

NOTE: The Python glsapiutil.py and glsapiutil3.py classes are now available on GitHub. GitHub has the most current libraries. glsapiutil3.py works with both Python v2 and v3.

Legacy Overview

The GLSRestApiUtils utility class provides a consistent way to perform common REST operations, such as REST HTTP methods or common XML string manipulation. It is a utility class written in Python and Groovy for the API Cookbook examples. This utility class is specific to the Cookbook examples. The class is not required for the API with Groovy or Python, as there are many other ways to manipulate HTTP and XML in these languages. However, it is required if you want to run the Cookbook examples as written. It is also not part of REST or EPP/automation.

Using Utility Calls in your Scripts

Almost all Cookbook example files use the HTTP methods from the GLSRestApiUtils class.

The HTTP method calls in Groovy resemble the following example:

returnNode = GLSRestApiUtils.httpGET(uri, username, password)
returnNode = GLSRestApiUtils.httpPUT(inputNode, uri, username, password)
returnNode = GLSRestApiUtils.httpPOST(inputNode, uri, username, password)

In this example, the returnNode and inputNode are Groovy nodes containing XML. The XML in the returnNode contains the XML available from the server after a successful method call. If the method call was unsuccessful, the XML contains error information. The following is an example of the XML manipulation functions in the utility:

println GLSRestApiUtils.nodeToXmlString(returnNode)

As you can see from these examples, the utility class is easy to include in your scripting. The code is contained in the GLSRestApiUtils files attached to this page.

Deploying Groovy and Python scripts

Deploying a Groovy Script that Uses the Utility Class

To deploy a Groovy script that uses the utility class, you must include the directory containing GLSRestApiUtils.groovy in the Groovy class path.

Groovy provides several ways to package and distribute source files, including the following methods:

• Call Groovy with the -classpath (or -cp) parameter.

• Add to the CLASSPATH environment variable.

• Create a ~/.groovy/lib directory for jar files for common libraries.

If you would like to experiment with the Cookbook examples, you can also copy the file into the same directory as the example script.

Use the Python Library

Library functions

The HTTP method calls for the Python version of the library resemble the following:

returnXML = api.GET( uri )
returnXML = api.PUT( xml, uri )
returnXML = api.POST( xml, uri )

Unlike with the Groovy library, the rest functions in the Python library require XML (text) as input (not DOM nodes). The return values of the GET, PUT, and POST functions are also XML text.

Deploy Scripts with the Python Library in Clarity LIMS (v4 and Later)

If a script must work with a running process or step, it is normal to use either the {processURI:v2} or the {stepURI:v2} tokens. The following example has the {stepURI:v2} token:

bash -l -c "/usr/bin/env python /opt/gls/clarity/customextensions/myScript.py 
-u {username} -p {password} -s {stepURI:v2} -f {compoundOutputFileLuid0}"

In Clarity LIMS v4 and above, these tokens sometimes resolve to https://localhost:9080/api/v2/... instead of the expected HOSTNAME. Setting up the API object with a hostname other than https://localhost:9080 can cause Access Denied errors. To avoid this issue, alter the API authentication code slightly as follows.

import platform

HOSTNAME = platform.node() # get the system hostname
VERSION = 'v2' # API version 2
BASE_URI = HOSTNAME + '/api/' + VERSION + '/'

USERNAME = 'username'
PASSWORD = 'password'
api = None

[...]

def setupGlobalsFromURI( uri ):

    global HOSTNAME
    global VERSION
    global BASE_URI

    tokens = uri.split( '/' )
    HOSTNAME = '/'.join( tokens[0:3] )
    VERSION = tokens[4]
    BASE_URI = '/'.join( tokens[0:5] ) + '/'

def main():
    global api
    api = glsapiutil.glsapiutil2() #initialise the API object, using version 2 of the API

    setupGlobalsFromURI( args.stepURI ) # assuming the step URI was passed by the EPP / automation trigger

    api.setHostname( HOSTNAME ) # set the hostname, currently taken from the system
    api.setVersion( VERSION ) # the version, currently set to 'v2'
    api.setup( USERNAME, PASSWORD ) # authenticate with the Clarity LIMS API user credentials 

TThe changes are highlighted in red. This code takes the resolved {stepURI:v2} token (assumed to be stored in the args object) and resets the HOSTNAME variable to the new value (eg, https://localhost:9080) before authenticating.

These changes are fully backward-compatible with Clarity LIMS v4 or earlier. The EPP/automation URI tokens resolve to the expected hostname, and the setupGlobalsFromURI() function still parses it correctly.

NOTE: On GitHub, in addition to the libraries, a basic_complete_recipe.py script that contains the skeleton code is needed to get started with the Python API. This script also includes the modifications required to work with Clarity LIMS v4 and later. The legacy Groovy library can still be obtained using the attachment.

Attachments

GLSRestApiUtils.groovy:

10KB

GLSRestApiUtils.groovy