6.2.11 Accessing MWS REST Resources

Often a plugin type may need to access existing MWS REST Resources in order to extend or complement default MWS functionality. This can be done with the 6.6.2 Moab HPC Suite REST Service, which allows a plugin type developer to utilize the existing Resources documentation (see Chapter 4: Resources) to perform these tasks.

All accesses to resources require an HTTP method to use (such as GET, POST, PUT, or DELETE) and a relative URL (such as /rest/jobs). Although it mimics the REST resource interface, no actual requests are made and no data is transmitted through the network.

Authentication

All resources are available to the Moab HPC Suite REST Service, and no authentication or Application Accounts are needed.

Caution must be used when developing plugin types, as there are no restrictions to what may be done with the Moab HPC Suite REST Service. This is especially true when not utilizing hooks as discussed below.

Hooks

If pre and post-processing hooks are utilized in MWS (3.7  Pre- and Post-Processing Hooks), the plugin type developer can choose whether or not they are executed when performing a 'request' through the Moab HPC Suite REST service. This is done through the hooks option as documented in 6.6.2 Moab HPC Suite REST Service.

Verifying API Version Support

The Moab HPC Suite REST Service provides a method for easily determining which API versions are supported by the current version of MWS. This method includes checks to make sure that the API version will work as expected, including verifying any configuration or external services are running.

moabRestService.isAPIVersionSupported(1)
moabRestService.isAPIVersionSupported(2)

Converting String Dates

Because the Moab HPC Suite REST Service returns data exactly as given to an external consumer of MWS, including dates converted to strings, the service provides a method for converting MWS date strings to actual Date objects.

moabRestService.convertDateString("2024-11-08 13:18:47 MST")

URL Parameters

URL parameters, such as query, sort, proxy-user, and others should not be appended directly to the URL. Instead, these can be specified with the params option:

// Query images that are hypervisors
moabRestService.get("/rest/images", params:[query:'{"hypervisor":true}'])
// Sort images by osType
moabRestService.get("/rest/images", params:[sort:'{"osType":1}'])

Examples

This code retrieves a list of all nodes, and is equivalent to the Get All Nodes task:

package example

import com.adaptc.mws.plugins.*
import net.sf.json.*

class RestPlugin {
	IMoabRestService moabRestService

	public void poll() {
		def result = moabRestService.get("/rest/nodes")
		// OR with the hook enabled…
		def result = moabRestService.get("/rest/nodes", hooks:true)

		assert result instanceof MoabRestResponse
		assert nodes instanceof List

		log.debug("Nodes list:")
		nodes.each { JSON node ->
			log.debug(node.id)
		}
	}
}

This code adds a flag to a job, and is equivalent to the Modify Job Attributes task. This request also enables the hook (if one is configured) for the 'request' and uses a URL parameter. This is the equivalent of making a call to /rest/jobs/job.1?proxy-user=adaptive.

package example

import com.adaptc.mws.plugins.*
import net.sf.json.*

class RestPlugin {
	IMoabRestService moabRestService

	public void poll() {
		def jobId = "job.1"
		def result = moabRestService.put("/rest/jobs/"+jobId, hooks:true, params:
['proxy-user':'adaptive']) {
			[flags:["RESTARTABLE"]]
		}
		assert result.isSuccess()
	}
}