The sections below show the MWS resources and the HTTP methods defined on them. The prefix for these resources depends on how the mws.war file is deployed. A typical prefix would be http://localhost:8080/mws. Using this example, one absolute resource URI would be http://localhost:8080/mws/rest/jobs.

3.1 Access Control Lists

This section describes behavior of the ACL Rules (Access Control List Rules) object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The ACL API contains the type and description of all fields in the ACL Rules object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

ACLs are not directly manipulated through a single URL, but with sub-URLs of the other objects such as Virtual Containers and Reservations.

Resource	GET	PUT	POST	DELETE
/rest/reservations/rsvId/acl-rules/aclId		Create or Update ACLs		Delete ACL
/rest/vcs/vcId/acl-rules/aclId		Create or Update ACLs		Delete ACL

3.1.1 Getting ACLs

Although ACL Rules cannot be retrieved directly using the GET method on any of the acl-rules resources, ACL Rules are attached to supported objects when querying for them. Each supported object contains a field named aclRules, which is a collection of the ACL Rules defined on that object.

Supported Objects

The following is a list of objects that will return ACL Rules when queried:

3.1.2 Creating or Updating ACLs

The HTTP PUT method is used to create or update ACL Rules. The payload can contain one or more ACL Rules. If an ACL Rule with the same type and value exists, then it will be overwritten.

Quick Reference

PUT http://localhost/mws/rest/reservations/<rsvId>/acl-rules
PUT http://localhost/mws/rest/vcs/<vcId>/acl-rules

3.1.2.1 Create or Update ACL

URLs and Parameters

PUT http://localhost/mws/rest/reservations/<objectId>/acl-rules
PUT http://localhost/mws/rest/vcs/<objectId>/acl-rules

Parameter	Required	Type	Valid Values	Description
objectId	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available for the PUT method, along with some sample values.

JSON Payload

{"aclRules": [{
  "affinity": "POSITIVE",
  "comparator": "LEXIGRAPHIC_EQUAL",
  "type": "USER",
  "value": "ted"
}]}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["Virtual container 'vc1' successfully modified"]}

Samples

Create or update multiple ACLs on a single object:

PUT http://localhost/mws/rest/reservations/system.21/acl-rules

{"aclRules": [
    {
    "affinity": "POSITIVE",
    "comparator": "LESS_THAN_OR_EQUAL",
    "type": "DURATION",
    "value": "3600"
  },
    {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "ted"
  }
]}

Restrictions

ACL Rules cannot be added to or updated on Standing Reservations.
The affinity and comparator fields are ignored for Virtual Containers.

3.1.3 Deleting ACLs

The HTTP DELETE method is used to remove ACL Rules.

Quick Reference

ACL Rules cannot be removed from Standing Reservations.

DELETE http://localhost/mws/rest/reservations/<rsvId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<vcId>/acl-rules/<aclId>

3.1.3.1 Delete ACL

URLs and Parameters

DELETE http://localhost/mws/rest/reservations/<objectId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<objectId>/acl-rules/<aclId>

Parameter	Required	Type	Valid Values	Description
objectId	Yes	String	-	The unique identifier of the object from which to remove the ACL Rule.
aclId	Yes	String	-	A string representing the ACL Rule, with the format `type:value`.

See Global URL Parameters for available URL parameters.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["Successfully modified virtual container 'vc1'"]}

Restrictions

ACL Rules cannot be removed from Standing Reservations.

3.2 Diagnostics

This section describes additional REST calls that are available for performing diagnostics on Moab Web Services.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/diag/about	Get version information

3.2.1 Version and Build Information

The HTTP GET method is used to retrieve version and build information.

Quick Reference

GET http://localhost/mws/rest/diag/about

URLs and Parameters

GET http://localhost/mws/rest/diag/about

Sample Response

The response contains the application version, build number, build date, and revision.

{
  "version":"7.0",
  "build":"100",
  "buildDate":"2012-01-01_16-00-00",
  "revision":"1000"
}

3.3 Images

This section describes behavior of the Image resource in Moab Web Services. An image resource is used to track the different types of operating systems and hypervisors available in the data center. It also tracks which virtual machines are available on the hypervisors. This section describes the URLs, payloads, and responses delivered to and from Moab Web Services.

The Image API contains the type and description of all fields in the Image object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/images	Get All Images		Create Image
/rest/images/id	Get Specified Image	Modify Image		Delete Image
/rest/images/name	Get Specified Image	Modify Image		Delete Image

3.3.1 Getting Images

The HTTP GET method is used to retrieve Image information. You can query all objects or a single object.

Quick Reference

GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>
GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]

3.3.1.1 Get All Images

URLs and Parameters

GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"stateful","osType":"linux"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":-1}

It is possible to query images by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/images?fields=id,name

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "centos5-stateful"
  }]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters

3.3.1.2 Get Single Image

URLs and Parameters

GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

GET http://localhost/mws/rest/images/centos5-compute-stateful

{
  "active":true,
  "extensions":{
    "xcat":{
      "os":"centos",
      "architecture":"x86_64",
      "profile":"compute"
    }
  },
  "features":[],
  "hypervisor":false,
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos5-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":false,
  "supportsVirtualMachine":true,
  "templateName":"",
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. See Modify Image for more information.

3.3.2 Creating Images

The HTTP POST method is used to submit Images.

Quick Reference

POST http://localhost/mws/rest/images

3.3.2.1 Create Single Image

URLs and Parameters

POST http://localhost/mws/rest/images

See Global URL Parameters for available URL parameters.

Request Body

Three fields are required to submit an image: name, hypervisor, and osType. Each image must also support provisioning to either a physical machine or a virtual machine by using the supportsPhysicalMachine or supportsVirtualMachine fields.

The name field must contain only letters, digits, periods, dashes, and underscores.

The array of virtualized images are themselves objects that contain image IDs or names. For more information on available fields and types, see the Image API.

The following is an example of the most basic image that can be created:

POST http://localhost/mws/rest/images

{
  "name": "centos5-stateful",
  "osType": "linux",
  "hypervisor": false,
  "supportsVirtualMachine":true
}

Note that this example does not provide any information for a provisioning manager (such as xCAT) to actually provision the machine. In order to provide this, you must add an entry to the extensions field that contains provisioning manager-specific information. Each key in the extensions field corresponds to the provisioning manager, and certain properties are required based on this key. For example, the xCAT extension key must be named xcat and must contain certain fields. These extension keys are documented in the Image API. See the following examples of creating images with xCAT-specific provisioning information below.

Sample Response

If the request was successful, the response body is the new image that was created exactly as shown in Get Single Image. On failure, the response is an error message.

Samples

The virtualizedImages field only accepts input when the image is a hypervisor and expects an array of image IDs or names, as shown in the following example:

Example payload of hypervisor with 2 vms

{
  "hypervisor":true,
  "name":"esx5-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "type":"stateful",
  "virtualizedImages":   [
    {"id": "4fa197e68ca30fc605dd1cf0"},
    {"name": "centos5-stateful"}
  ]
}

The following example shows how to create an image that utilizes a cloned template for a virtual machine. (Note that the type must be set to linkedclone in order to set the templateName field.)

VM Utilizing a Cloned Template

{
  "active": true,
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "linkedclone",
  "supportsVirtualMachine":true,
  "templateName":"centos5-compute"
}

The following are samples of a virtual machine and a hypervisor image that can be provisioned with xCAT:

xCAT Virtual Machine Image

{
  "active": true,
  "features": [],
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "stateful",
  "supportsVirtualMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "centos",
        "architecture": "x86_64",
        "profile": "compute"
     }
  }
}

xCAT Hypervisor Image

{
  "active": true,
  "features": [],
  "hypervisor": true,
  "name": "esxi5-base-stateless",
  "osType": "linux",
  "virtualizedImages":   [
    {"name": "centos5-compute-stateless"}
  ],
  "type": "stateless",
  "supportsPhysicalMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "esxi5",
        "architecture": "x86_64",
        "profile": "base",
        "hvType": "esx",
        "hvGroupName": "esx5hv",
        "vmGroupName": "esx5vm"
     }
  }
}

3.3.3 Modifying Images

The HTTP PUT method is used to modify Images.

Quick Reference

PUT http://localhost/mws/rest/images/<id>
PUT http://localhost/mws/rest/images/<name>

3.3.3.1 Modify Single Image

URLs and Parameters

PUT http://localhost/mws/rest/image/<id>
PUT http://localhost/mws/rest/image/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

The name field must contain only letters, digits, periods, dashes, and underscores.

Example Request

PUT http://locahost/mws/rest/image/centos5-stateful

{
  "name": "centos5-stateful",
  "type": "stateful",
  "hypervisor": false,
  "osType": "linux",
  "virtualizedImages": []
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object in between the time the data was retrieved and the modify request was delivered.

Sample Response

If the request was successful, the response body is the modified image as shown in Get Single Image. On failure, the response is an error message.

3.3.4 Deleting Images

The HTTP DELETE method is used to delete Images.

Quick Reference

DELETE http://localhost/mws/rest/images/<id>
DELETE http://localhost/mws/rest/images/<name>

3.3.4.1 Delete Single Image

URLs and Parameters

DELETE http://localhost/mws/rest/image/<id>
DELETE http://localhost/mws/rest/image/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Image.
name	Yes	String	-	The name of the Image.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{}

3.4 Jobs

This section describes behavior of the Job object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Job API contains the type and description of all fields in the Job object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/jobs	Get all jobs		Submit new job
/rest/jobs/active	Get all active jobs
/rest/jobs/complete	Get all complete jobs
/rest/jobs/id	Get specified job	Modify job		Cancel job
/rest/jobs/active/id	Get specified active job
/rest/jobs/complete/id	Get specified complete job

3.4.1 Getting Job Information

The HTTP GET method is used to retrieve Job information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/jobs/<id>

3.4.1.1 Get All Jobs

URLs and Parameters

GET http://localhost/mws/rest/jobs

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "...",
	…
  }]
}

Samples

GET http://localhost/mws/rest/jobs?fields=id,state,flags

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
        {
      "id": "job.1",
      "state": "IDLE",
      "flags": ["PREEMPTABLE"]
    },
        {
      "id": "job.2",
      "state": "RUNNING",
      "flags": []
    },
        {
      "id": "job.3",
      "state": "REMOVED",
      "flags":       [
        "PREEMPTABLE",
        "RESTARTABLE"
      ]
    }
  ]
}

Known Issues

Some jobs are not returned if DisplayFlags UseBlocking is set in the moab.cfg file.

3.4.1.2 Get All Active Jobs

URLs and Parameters

GET http://localhost/mws/rest/jobs/active

See Global URL Parameters for available URL parameters.

Sample Response

Same as Get All.

3.4.1.3 Get All Complete Jobs

URLs and Parameters

GET http://localhost/mws/rest/jobs/complete

See Global URL Parameters for available URL parameters.

Sample Response

Same as Get All.

Known Issues

This query can take a long time and slow down the Moab Workload Manager, especially on systems with many completed jobs. Avoid this query if possible.

3.4.1.4 Get Single Job

URLs and Parameters

GET http://localhost/mws/rest/jobs/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "account": "account",
  "activeDuration": 150,
  "allocatedNodes": [{"id": "node01"}],
  "allocatedVMs": [{"id": "vm1"}],
  "blockReason":   {
    "message": "Check valid user",
    "type": "BADUSER"
  },
  "bypass": 5,
  "commandFile": "/tmp/test.sh",
  "commandLineArguments": "-x -v",
  "completionCode": 0,
  "completionDate": "2011-11-08 13:18:47 MST",
  "dedicatedProcessorSeconds": 1.5,
  "destinationRmJobId": "1000011",
  "earliestStartDate": "2011-11-08 13:18:47 MST",
  "earliestStartDateRequested": "2011-11-08 13:18:47 MST",
  "effectivePartitionAccessList": ["ALL"],
  "effectiveQueueDuration": 600,
  "emailNotifyTypes": ["END"],
  "emailNotifyUsers": ["[email protected]"],
  "environmentVariables": {"var1": "val1"},
  "expectedState": "IDLE",
  "flags": ["RESTARTABLE"],
  "genericAttributes": ["attr1"],
  "group": "group",
  "holds": ["USER"],
  "hosts": ["host1"],
  "id": "Moab.1",
  "initialWorkingDirectory": "/tmp",
  "latestCompletedDateRequested": "2011-11-08 13:18:47 MST",
  "masterHost": "masterHost",
  "memoryRequested": 1024,
  "messages": [  {
    "creationTime": null,
    "expireTime": null,
    "index": 0,
    "message": "Message one",
    "messageCount": 0,
    "author": "moab",
    "priority": 0
  }],
  "name": "myJob",
  "os": "linux",
  "partitionAccessList": ["ALL"],
  "qos": "QOS1",
  "qosRequested": "QOS1",
  "queue": "BATCH",
  "queueStatus": "ACTIVE",
  "durationRequested": 300,
  "requirements": [  {
    "allocatedNodes": [{"id": "node01"}],
    "allocatedPartition": "",
    "genericResources":     {
      "resource1": 10,
      "resource2": 30
    },
    "nodeAccessPolicy": null,
    "preferredNodeFeatures": [],
    "requiredArchitecture": "",
    "requiredClass": "",
    "requiredDiskPerTask": 0,
    "requiredMemoryPerTask": 0,
    "requiredNetwork": "",
    "requiredNodeCountMinimum": 0,
    "requiredNodeDisk": 0,
    "requiredNodeFeatures": [],
    "requiredNodeMemory": 0,
    "requiredNodeProcessors": 0,
    "requiredNodeSwap": 0,
    "requiredPartition": "",
    "requiredProcessorCountMinimum": 4,
    "requiredProcessorsPerTask": 0,
    "requiredSwapPerTask": 0,
    "tasksPerNode": 0
  }],
  "reservationRequested": "rsv.1",
  "reservationStartDate": "2011-11-08 13:18:47 MST",
  "rmExtension": "x=PROC=4",
  "rmName": "torque",
  "rmStandardErrorFilePath": "/tmp/error.out",
  "rmStandardInputFilePath": "/tmp/input.in",
  "rmStandardOutputFilePath": "/tmp/output.out",
  "runPriority": 5,
  "sourceRmJobId": "1000011",
  "standardErrorFilePath": "/tmp/job.error.out",
  "standardOutputFilePath": "/tmp/job.output.out",
  "startCount": 1,
  "startDate": "2011-11-08 13:18:47 MST",
  "startPriority": 2,
  "state": "COMPLETED",
  "submitDate": "2011-11-08 13:18:47 MST",
  "submitHost": "admin-node",
  "suspendDuration": 60,
  "systemPriority": 6,
  "userPriority": 5,
  "user": "saadmin",
  "variables": {"var1": "val1"},
  "virtualContainers": [{"id":"vc1"}],
  "vmUsagePolicy": "CREATEVM"
}

3.4.1.5 Get Single Active Job

URLs and Parameters

GET http://localhost/mws/rest/jobs/active/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

Same as Get Single.

3.4.1.6 Get Single Active Job

URLs and Parameters

GET http://localhost/mws/rest/jobs/complete/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

Same as Get Single.

3.4.2 Submitting Jobs

The HTTP POST method is used to submit Jobs.

Quick Reference

POST http://localhost/mws/rest/jobs[?proxy-user=<username>]

Restrictions

The user given in user must have read access to the file given in commandFile.
No more than one virtual container can be specified in the request. The virtual container must already exist.
The user and group properties are used to submit a job as the specified user belonging to the specified group.
Job variables have the following restrictions:

variable names cannot contain equals (=), semicolon (;), colon (:), plus (+), question mark (?), caret (^), backslash (\), or white space.
variable values cannot contain semicolon (;), colon (:), plus (+), or caret (^).

When submitting jobs, the only supported hold type is USER.
The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.4.2.1 Submit Job with Host List

URLs and Parameters

POST http://localhost/mws/rest/jobs[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

To submit a job with a specified host list, only two fields are required: commandFile and hosts.

The payload below shows all the fields that are available during job submission.

JSON Payload (specified host list)

{
  "account": "project name",
  "commandFile": "/tmp/myscript.sh",
  "commandLineArguments": "-x",
  "earliestStartDateRequested": "2011-09-26 16:28:20 MDT",
  "emailNotifyTypes": ["END"],
  "emailNotifyUsers": ["[email protected]"],
  "environmentRequested": true,
  "environmentVariables":   {
    "SHELL": "/bin/bash",
    "LC_ALL": "en_US.utf8"
  },
  "flags":   [
    "SUSPENDABLE",
    "BESTEFFORT"
  ],
  "group": "wheel",
  "holds": ["USER"],
  "hosts":   [
    "node2",
    "node3"
  ],
  "initialWorkingDirectory": "/tmp",
  "name": "job name",
  "os": "Ubuntu",
  "qosRequested": "highprio",
  "queue": "priority",
  "durationRequested": 3600,
  "requirements": [  {
    "genericResources":     {
      "resource1": 10,
      "resource2": 30
    },
    "nodeAccessPolicy": "SHARED",
    "requiredArchitecture": "x86_64",
    "requiredDiskPerTask": 500,
    "requiredMemoryPerTask": 1024,
    "requiredNodeFeatures": ["bluray"],
    "requiredPartition": "cs",
    "requiredProcessorsPerTask": 3,
    "requiredSwapPerTask": 600,
    "tasksPerNode": 8
  }],
  "reservationRequested": "grid.3",
  "standardErrorFilePath": "/home/jacob/err",
  "standardOutputFilePath": "/home/jacob/out",
  "submitHost": "admin-node",
  "templateList":   [
    "template1",
    "template2"
  ],
  "user": "jacob",
  "userPriority": 25,
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "virtualContainers": [{"id": "vc1"}],
  "vmUsagePolicy": "REQUIREPM"
}

Sample Response

The response of this task is one of three possibilities:

An object with a single messages property containing a list of error messages on failure

{"messages":["Could not create job - invalid requirements"]}

An object with an id property containing the ID of the newly created job

{"id":"Moab.1"}

An object with an id property and a virtualContainers list containing the ID of the newly created virtual container

{"id":"Moab.1","virtualContainers":[{"id":"vc1"}]}

The virtual container will only be reported when a new virtual container has been created by Moab for the job.

3.4.2.2 Submit Job with Node Count

URLs and Parameters

POST http://localhost/mws/rest/jobs[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

To submit a job with a specified node count, only two fields are required: commandFile and requiredProcessorCountMinimum (in the requirements array).

The payload below shows all the fields that are available during job submission.

JSON Payload (specified node count)

{
  "account": "project name",
  "commandFile": "/tmp/myscript.sh",
  "commandLineArguments": "-x",
  "earliestStartDateRequested": "2011-09-26 16:28:20 MDT",
  "emailNotifyTypes": ["END"],
  "emailNotifyUsers": ["[email protected]"],
  "environmentRequested": true,
  "environmentVariables":   {
    "SHELL": "/bin/bash",
    "LC_ALL": "en_US.utf8"
  },
  "flags":   [
    "SUSPENDABLE",
    "BESTEFFORT"
  ],
  "group": "wheel",
  "holds": ["USER"],
  "initialWorkingDirectory": "/tmp",
  "name": "job name",
  "os": "Ubuntu",
  "qosRequested": "highprio",
  "queue": "priority",
  "durationRequested": 3600,
  "requirements": [  {
    "genericResources":     {
      "resource1": 10,
      "resource2": 30
    },
    "nodeAccessPolicy": "SHARED",
    "requiredArchitecture": "x86_64",
    "requiredDiskPerTask": 500,
    "requiredMemoryPerTask": 1024,
    "requiredNodeFeatures": ["bluray"],
    "requiredPartition": "cs",
    "requiredProcessorCountMinimum": 4,
    "requiredProcessorsPerTask": 3,
    "requiredSwapPerTask": 600,
    "tasksPerNode": 8
  }],
  "reservationRequested": "grid.3",
  "standardErrorFilePath": "/home/jacob/err",
  "standardOutputFilePath": "/home/jacob/out",
  "submitHost": "admin-node",
  "templateList":   [
    "template1",
    "template2"
  ],
  "user": "jacob",
  "userPriority": 25,
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "virtualContainers": [{"id": "vc1"}],
  "vmUsagePolicy": "REQUIREPM"
}

Sample Response

The response of this task is the same as submitting a job with a host list.

3.4.2.3 Examples of Job Submission

This section includes some sample job submission requests.

Submit job to run on node2 and node3

POST http://localhost/mws/rest/jobs

{
  "commandFile": "/tmp/test.sh",
  "group": "adaptive",
  "hosts":   [ "node2", "node3" ]
  "initialWorkingDirectory": "/tmp",
  "user": "adaptive",
}

Submit job that requires 20 processors

POST http://localhost/mws/rest/jobs

{
  "commandFile": "/tmp/test.sh",
  "group": "adaptive",
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"requiredProcessorCountMinimum": "20"}]
  "user": "adaptive",
}

Submit job to run after a certain time

POST http://localhost/mws/rest/jobs

{
  "commandFile": "/tmp/test.sh",
  "earliestStartDateRequested": "2012-08-26 16:28:20 MDT",
  "group": "adaptive",
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"requiredProcessorCountMinimum": "20"}]
  "user": "adaptive",
}

Submit job based on `msub` example

Given this msub command:

msub -l nodes=3:ppn=2,walltime=1:00:00,pmem=100 script2.pbs.cmd

Here is an equivalent MWS request:

POST http://localhost/mws/rest/jobs

{
  "user": "adaptive",
  "group": "adaptive",
  "initialWorkingDirectory": "/home/adaptive",
  "commandFile": "/home/adaptive/script2.pbs.cmd",
  "requirements": [  {
    "requiredProcessorCountMinimum": 6,
    "tasksPerNode": 2,
    "requiredMemoryPerTask": 100
  }],
  "durationRequested": 3600
}

To emulate what msub does, make commandFile an absolute path, and add user, group, and initialWorkingDirectory.

As shown above, nodes=3:ppn=2 is equivalent to setting requiredProcessorCountMinimum to 6 and tasksPerNode to 2.

3.4.3 Modifying Jobs

The HTTP PUT method is used to modify Jobs.

Quick Reference

PUT http://localhost/mws/rest/jobs/<id>[/<modifyAction>][?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.4.3.1 Modify Job Attributes

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

JSON Payload

{
  "account": "engineering",
  "earliestStartDateRequested": "2011-08-24 15:02:00",
  "flags":   [
    "RESTARTABLE",
    "SUSPENDABLE"
  ],
  "holds": ["USER"],
  "messages":   [
    {"message": "First message"},
    {"message": "Second message"}
  ],
  "name": "EngineeringJob",
  "qosRequested": "NORMAL",
  "queue": "BATCH",
  "durationRequested": 600,
  "requirements": [{"requiredPartition": "msm"}],
  "reservationRequested": "rsv.1",
  "trigger": "triggerString",
  "userPriority": 10,
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

These messages may not match the messages returned from Moab exactly, but are given as an example of the structure of the response.

Not all messages are shown for the above payload.

JSON Response

{
  "messages":[
    "Account modified successfully",
    "Messages modified successfully",
    "Variables modified successfully"
  ]
}

Restrictions

Old messages are not removed from jobs; only new messages are added.
Job variables have the restrictions documented in Submitting Jobs

3.4.3.2 Perform Actions on Job

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<id>/<modifyAction>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
modifyAction	Yes	String	cancel	Attempts to cancel the job.
			checkpoint	Attempts to checkpoint the job. Note that the OS must support checkpointing for this to work.
			execute	Executes the job if possible.
			hold	Attempts to hold the job using the holds set in the payload.
			requeue	Attempts to requeue the job.
			resume	Attemps to resume the job.
			suspend	Attempts to suspend the job.
			unhold	Attempts to release the holds set in the payload.
proxy-user	No	String	-	Perform the action as this user.

Performing a cancel function on a job is equivalent to deleting a job.

See Global URL Parameters for available URL parameters.

Payload

Payloads are only required for holding or unholding jobs. All other actions do not require payloads of any kind.

JSON Payload to Add Holds to a Job

{
  "holds": ["USER"]
}

JSON Payload to Remove Holds from a Job

{
  "holds": ["USER"]
}

If no holds are specified when unholding a job, all holds will be removed. This is equivalent to specifying holds as a list with a single element of ALL.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{
  "messages":[
    "Job modified successfully"
  ]
}

3.4.4 Deleting (Canceling) Jobs

The HTTP DELETE method is used to cancel Jobs.

Quick Reference

DELETE http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.4.4.1 Cancel Job

URLs and Parameters

DELETE http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

Additional information about the DELETE can be found in the HTTP response header X-MWS-Message.

3.5 Job Templates

This section describes behavior of the Job Template object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Job Template API contains the type and description of all fields in the Job Template object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/job-templates	Get all job templates
/rest/job-templates/id	Get specified job template

3.5.1 Getting Job Templates

The HTTP GET method is used to retrieve Job Template information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/job-templates/<id>

3.5.1.1 Get All Job Templates

URLs and Parameters

GET http://localhost/mws/rest/job-templates

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/job-templates?fields=id

{
  "totalCount": 14,
  "resultCount": 14,
  "results":   [
    {"id": "DEFAULT"},
    {"id": "genericVM"},
    {"id": "genericVM-setup"},
    {"id": "genericVM-destroy"},
    {"id": "genericVM-migrate"},
    {"id": "genericPM"},
    {"id": "genericPM-setup"},
    {"id": "genericPM-destroy"},
    {"id": "OSStorage"},
    {"id": "OSStorage-setup"},
    {"id": "OSStorage-destroy"},
    {"id": "extraStorage"},
    {"id": "extraStorage-setup"},
    {"id": "extraStorage-destroy"}
  ]
}

3.5.1.2 Get Single Job Template

URLs and Parameters

GET http://localhost/mws/rest/job-templates/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "account": "account",
  "args": "arg1 arg2",
  "commandFile": "/tmp/script",
  "description": "description",
  "genericSystemJob": true,
  "id": "genericVM",
  "inheritResources": false,
  "jobDependencies": [  {
    "name": "genericVM-setup",
    "type": "JOBSUCCESSFULCOMPLETE"
  }],
  "jobFlags": ["VMTRACKING"],
  "jobTemplateFlags": ["SELECT"],
  "jobTemplateRequirements": [  {
    "architecture": "x86_64",
    "diskRequirement": 500,
    "genericResources": {"tape": 3},
    "nodeAccessPolicy": "SINGLEJOB",
    "operatingSystem": "Ubuntu 10.04.3",
    "requiredDiskPerTask": 200,
    "requiredFeatures": ["dvd"],
    "requiredMemoryPerTask": 1024,
    "requiredProcessorsPerTask": 2,
    "requiredSwapPerTask": 512,
    "taskCount": 4
  }],
  "priority": 20,
  "qos": "qos",
  "queue": "queue",
  "durationRequested": 600,
  "select": true,
  "trigger": null,
  "version": 0,
  "vmUsagePolicy": "REQUIREPM"
}

3.6 Nodes

This section describes behavior of the Node object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Node API contains the type and description of all fields in the Node object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/nodes	Get all nodes
/rest/nodes/id	Get specified node	Modify node

3.6.1 Getting Nodes

The HTTP GET method is used to retrieve Node information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/nodes/<id>

3.6.1.1 Get All Nodes

URLs and Parameters

GET http://localhost/mws/rest/nodes

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/nodes?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "node1"},
    {"id": "node2"},
    {"id": "node3"}
  ]
}

3.6.1.2 Get Single Node

URLs and Parameters

GET http://localhost/mws/rest/nodes/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "accessPolicy": null,
  "aliases": [],
  "architecture": "",
  "availableClasses": [],
  "availableDisk": -1,
  "availableEndDate": null,
  "availableGenericResources": {},
  "availableMemory": -1,
  "availableProcessors": -1,
  "availableStartDate": null,
  "availableSwap": -1,
  "blockReason": "",
  "comments": "",
  "configuredClasses": [],
  "cpuLoad": 0,
  "dynamic": false,
  "externalLoad": 0,
  "features": [],
  "flags":   [
    "VM_CREATE_ENABLED",
    "RM_DETECTED"
  ],
  "genericEvents": [],
  "genericMetrics": {},
  "genericResources": {},
  "hypervisorType": "",
  "iOLoad": 0,
  "id": "",
  "index": -1,
  "jobs": [{"id": "Moab.1"}],
  "lastStateUpdateDate": null,
  "lastUpdateDate": null,
  "maxIOIn": 0,
  "maxIOLoad": 0,
  "maxIOOut": 0,
  "maxJob": 0,
  "maxJobPerUser": 0,
  "maxLoad": 0,
  "maxPEPerJob": 0,
  "maxPageIn": 0,
  "maxPageOut": 0,
  "maxProc": 0,
  "maxProcPerClass": 0,
  "messages": [],
  "network": "",
  "networkAddress": "",
  "networkLoad": 0,
  "nextOS": "",
  "operations": [],
  "os": "",
  "osList": [],
  "overcommit": null,
  "partition": "",
  "power": null,
  "powerPolicy": null,
  "powerSelected": null,
  "priority": 0,
  "priorityFunction": "",
  "procSpeed": 0,
  "profilingEnabled": false,
  "rack": 0,
  "reservationCount": 0,
  "reservations": [],
  "rmAccessList": "",
  "size": 1,
  "slot": 0,
  "speed": 1,
  "speedWeight": 1,
  "state": null,
  "substate": "",
  "taskCount": -1,
  "totalActiveTime": 0,
  "totalAvailableTime": 0,
  "totalDisk": -1,
  "totalMemory": -1,
  "totalProcessors": -1,
  "totalStatsTime": 0,
  "totalSwap": -1,
  "totalUpTime": 0,
  "type": "",
  "variables": {},
  "version": 0,
  "virtualMachines": [{"id": "vm1"}],
  "vmOsList": []
}

3.6.2 Modifying Nodes

The HTTP PUT method is used to modify Nodes.

Quick Reference

PUT http://localhost/mws/rest/nodes/<id>[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.6.2.1 Modify Node

URLs and Parameters

PUT http://localhost/mws/rest/nodes/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

Sample JSON Payload to Modify a Node

{
  "genericEvents": [  {
    "name": "event1",
    "message": "Sample message"
  }],
  "genericMetrics":   {
    "metric1": 3,
    "metric2": 5
  },
  "messages":   [
    "message1",
    "message2"
  ],
  "os": "linux",
  "partition": "local",
  "power": "off|on",
  "state": "Busy",
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":[
  "Successfully modified os to 'linux'",
  "Successfully powered node off"
]}

3.7 Pending Actions

This section describes behavior of the Pending Action object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Pending Action API contains the type and description of all fields in the Pending Action object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/pending-actions	Get all pending actions

3.7.1 Getting Pending Actions

The HTTP GET method is used to retrieve Pending Action information.

Quick Reference

GET http://localhost/mws/rest/pending-actions

3.7.1.1 Get All Pending Actions

URLs and Parameters

GET http://localhost/mws/rest/pending-actions

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/pending-actions

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "failureDetails": "",
    "hosts": ["hv3"],
    "id": "vmcreate-27",
    "maxDurationInSeconds": 3600,
    "migrationDestination": "",
    "migrationSource": "",
    "motivation": "requested by root",
    "pendingActionState": "RUNNING",
    "pendingActionType": "VMCREATE",
    "requester": "root",
    "serviceId": "Rhel55Vm.200",
    "startTime": "2011-11-15 21:57:55 MST",
    "substate": "installing",
    "targetOS": "",
    "topLevelServiceId": "Lamp.132",
    "vmId": "vm8"
  }]
}

Generic vs Non-Generic Types

If generic job templates are used in Moab, MWS may be configured to translate pending actions with the generic type to the proper type such as VMCREATE. This is done in the configuration file. The Quickstart Guide provides the default mappings for this feature, as well as an example of adding a custom mapping from a custom template name to the correct type.

The default mappings are shown in the table below. The available pending action types may be seen on the PendingActionType API page.

Template Name	Mapped Type
genericVM-setup	VMCREATE
genericVM-migrate	VMMIGRATE
genericVM-destroy	VMDESTROY
OSStorage-setup	VMSTORAGE
OSStorage-destroy	VMSTORAGEDESTROY
extraStorage-setup	STORAGE
extraStorage-destroy	STORAGEDESTROY
genericPM-setup	OSPROVISION

When generic mappings are used, MWS will match the first template mapping that the pending action ID ends with. For example, an ID of Moab.1.genericVM-setup will map the type to VMCREATE.

To enable mapping for a custom template name such as myCustomVM-setup, simply add the following line to the MWS configuration file. The value of the pending action type is case insensitive.

mws.pendingActions.mappings["myCustomVM-setup"] = "vmcreate"

MWS also provides the ability to enable or disable the display of generic pending actions (or those pending actions that are not mapped). This behavior is controlled by the mws.pendingActions.displayGeneric setting as shown below. A false value will prevent generic pending actions from being displayed, while a true value will display all pending actions. By default this value is true.

mws.pendingActions.displayGeneric = false

3.8 Plugins

This section describes behavior of the Plugin object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Plugin API page contains the type and description of all fields in the Plugin object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/plugins	Get all plugins		Create new plugin
/rest/plugins/id	Get specified plugin	Modify plugin		Delete plugin

3.8.1 Getting Plugins

The HTTP GET method is used to retrieve Plugin information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/plugins/<id>

3.8.1.1 Get All Plugins

URLs and Parameters

GET http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/plugins?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "plugin1"},
    {"id": "plugin2"},
    {"id": "plugin3"}
  ]
}

The plugin objects contain two additional fields that are not in the API documentation: nextPollDate and lastPollDate. These represent that next and last date that polling will occur or has occurred. The values may also be null if polling has not occurred or if the plugin is in the STOPPED state.

3.8.1.2 Get Single Plugin

URLs and Parameters

GET http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED",
  "nextPollDate":"2011-12-02 17:28:52 MST",
  "lastPollDate":"2011-12-02 17:28:22 MST"
}

The plugin object contains two additional fields that are not in the API documentation: nextPollDate and lastPollDate. These represent the next and last date that polling will occur or has occurred. The values may also be null if polling has not occurred or if the plugin is in the STOPPED state.

3.8.2 Creating Plugins

The HTTP POST method is used to create Plugins.

Quick Reference

POST http://localhost/mws/rest/plugins

3.8.2.1 Create Plugin

URLs and Parameters

POST http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Payload

When creating a plugin, the id and pluginType fields are required. The payload below shows all fields that are available when creating a Plugin, along with some sample values.

JSON Payload

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  }
}

If a state is specified for the new plugin, it will be ignored.

Sample Response

JSON Response for successful POST

{"id": "plugin1"}

Restrictions

While it is possible to create a plugin with arbitrary nested configuration, such as:

…
"config":{
  "nestedObject":{
    "property1":"value1",
    "property2":"value2"
  },
  "nestedList:["listItem1", "listItem2"]
}

It is not recommended if using the user interface to manage plugins as it does not support editing or viewing any configuration data other than strings.

3.8.3 Modifying Plugins

The HTTP PUT method is used to modify Plugins.

Quick Reference

PUT http://localhost/mws/rest/plugins/<id>

3.8.3.1 Modify Plugin

URLs and Parameters

PUT http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when modifying a Plugin, along with some sample values.

JSON Payload for Plugin Modification

{
  "state":"STARTED",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED"
}

Sample Response

JSON Response

{"messages":["Plugin plugin1 updated", "Started Plugin 'plugin1'"]}

3.8.4 Deleting Plugins

The HTTP DELETE method is used to delete Plugins.

Quick Reference

DELETE http://localhost/mws/rest/plugins/<id>

3.8.4.1 Delete Plugin

URLs and Parameters

DELETE http://localhost/mws/rest/plugins/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

Additional information about a successful DELETE can be found in the HTTP response header X-MWS-Message.

JSON Response for an unsuccessful DELETE

{"messages":["Plugin plugin1 could not be deleted", "Error message describing the problem"]}

3.9 Plugin Types

This section describes behavior of the Plugin Type object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Plugin Type API page contains the type and description of all fields in the Plugin Type object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/plugin-types	Get all plugin types	Create or update plugin type
/rest/plugin-types/id	Get specified plugin type

3.9.1 Getting Plugin Types

The HTTP GET method is used to retrieve Plugin Type information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/plugin-types/<id>

3.9.1.1 Get All Plugin Types

URLs and Parameters

GET http://localhost/mws/rest/plugin-types

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/plugin-types?fields=id

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
    {"id": "MSM"},
    {"id": "Native"}
  ]
}

3.9.1.2 Get Single Plugin Type

URLs and Parameters

GET http://localhost/mws/rest/plugin-types/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "id":"Native",
  "author":"Adaptive Computing",
  "description":"Basic implementation of a native plugin",
  "instances":[
    {"id":"plugin1"}
  ]
}

3.9.2 Creating or Updating Plugin Types

The HTTP POST method is used to create or update Plugin Types. The Content-Type HTTP header is used to determine if the request contains a single class file as plaintext or the binary data of a JAR file. Each request is explained in the following sections.

Quick Reference

PUT http://localhost/mws/rest/plugin-types

3.9.2.1 Update Plugin Type (File)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types

See Global URL Parameters for available URL parameters.

Payload

This function is idempotent, meaning it will create the Plugin Type if it does not exist or update it if it does. The payload is the actual contents of the class file to upload. This web service is an exception to most as it requires a content type other than JSON. The preferred content type to use for this request is text/plain.

Plaintext upload

package testimport com.ace.mws.plugins.*
import com.ace.mws.plugins.exceptions.*
class UploadPlugin {
	static author = "Adaptive Computing"
	static description = "A sample plugin class"
	String id
	public void verifyConfiguration() throws InvalidPluginConfigurationException {
		def myConfig = config
		def errors = []
		if (!myConfig.arbitraryKey)
			errors << "Missing arbitraryKey!"
		if (errors)
			throw new InvalidPluginConfigurationException("Invalid plugin ${id} configuration", errors)
	}
	public def customService(Map params) {
		return params
	}
}

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the payload. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the get all plugin types task. The reason that the return of this task is a list is to accommodate the possibility of uploading multiple plugin types in a single JAR file as explained in the next section.

3.9.2.2 Update Plugin Type (JAR)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types

See Global URL Parameters for available URL parameters.

Payload

This function is idempotent, meaning it will create the Plugin Types if they do not exist or update them if they do. The payload is the binary contents of the JAR file to upload. This web service is an exception to most as it requires a content type of application/x-jar.

If the application/x-jar content type is not used in the request, it will be interpreted as a single class file, resulting in a failure to compile.

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the payload. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the get all plugin types task. Note that when using a JAR file, multiple plugin types may be uploaded in the same request.

3.10 Reports

This section describes behavior of the reporting framework in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Report, Sample, and Datapoint API contains the type and description of all fields in the Report, Sample, and Datapoint objects. They also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	POST	DELETE
/rest/reports	Get all reports	Create Reports	Deleting Reports
/rest/reports/name	Get single report with data
/rest/reports/id	Get single report with data
/rest/reports/name/datapoints	Get datapoints for report
/rest/reports/id/datapoints	Get datapoints for report
/rest/reports/name/samples	Get samples for report	Create sample(s) for report
/rest/reports/id/samples	Get samples for report	Create sample(s) for report

3.10.1 Getting Reports

The HTTP GET method is used to retrieve Report information. Queries for all reports with no attached data and a single report with associated data are available.

Quick Reference

GET http://localhost/mws/rest/reports/<id>
GET http://localhost/mws/rest/reports/<name>

3.10.1.1 Get All Reports (No Data Included)

URLs and Parameters

GET http://localhost/mws/rest/reports

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "3efe5c670be86ba8560397ff",
    "name": "cpu-util"
	…
  }]
}

No datapoints are returned when querying for all reports. To view the consolidated datapoints, the Get Single Report API call must be used.

Samples

GET http://localhost/mws/rest/reports?fields=id,name

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
        {
      "id": "3efe5c670be86ba8560397ff",
      "name": "cpu-util"
    },
        {
      "id": "3efe5c670be86ba856039800",
      "name": "cpu-temp"
    },
        {
      "id": "3efe5c670be86ba856039801",
      "name": "cpu-load"
    }
  ]
}

3.10.1.2 Get Single Report (Includes Data)

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>
GET http://localhost/mws/rest/reports/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

In the example below, the first datapoint has a null data element, which means that the minimumSampleSize configured for the report was not met when consolidating the datapoint. The second datapoint contains actual data.

JSON Response

{
  "consolidationFunction": "average",
  "datapointDuration": 15,
  "datapoints":   [
        {
      "endDate": "2011-12-02 17:28:22 MST",
      "startDate": "2011-12-02 17:28:22 MST",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:23 MST",
      "startDate": "2011-12-02 17:28:37 MST",
      "firstSampleDate": "2011-12-02 17:28:23 MST",
      "lastSampleDate": "2011-12-02 17:28:30 MST",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ],
  "description": "Example of CPU utilization reporting",
  "id": "3efe5c670be86ba8560397ff",
  "keepSamples": false,
  "minimumSampleSize": 1,
  "name": "cpu-util",
  "reportSize": 2
}

3.10.1.3 Get Datapoints For Single Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/datapoints
GET http://localhost/mws/rest/reports/<name>/datapoints

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

This function is exactly the same as requesting a single report with only the datapoints returned. No report metadata (i.e. description, minimumSampleSize, etc.) is returned.

JSON Response

{
  "resultCount":1,
  "totalCount":1,
  "results":[
        {
      "endDate": "2011-12-02 17:28:22 MST",
      "startDate": "2011-12-02 17:28:22 MST",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:37 MST",
      "startDate": "2011-12-02 17:28:37 MST",
      "firstSampleDate": "2011-12-02 17:28:23 MST",
      "lastSampleDate": "2011-12-02 17:28:23 MST",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ]
}

3.10.2 Getting Samples For Reports

The HTTP GET method is used to retrieve Sample information.

Quick Reference

GET http://localhost/mws/rest/reports/<id>/samples
GET http://localhost/mws/rest/reports/<name>/samples

3.10.2.1 Get Samples For Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/samples
GET http://localhost/mws/rest/reports/<name>/samples

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
	"timestamp": "2011-12-02 17:28:37 MST"
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	},
	…
  }]
}

3.10.3 Creating Reports

The HTTP POST method is used to create Reports. Operations are available to create reports with or without historical datapoints.

Quick Reference

POST http://localhost/mws/rest/reports

3.10.3.1 Create Report

URLs and Parameters

POST http://localhost/mws/rest/reports

See Global URL Parameters for available URL parameters.

Payload

To create a report, several fields are required as documented in the Report API.

The payload below shows all the fields that are available during report creation.

JSON Payload

{
	"name":"cpu-util",
	"description":"An example report on cpu utilization",
	"consolidationFunction":"average",
	"datapointDuration":15,
	"minimumSampleSize":1,
	"reportSize":2,
	"keepSamples":true,
	"datapoints":[
		{
			"startDate":"2011-12-01 19:16:57 MST",
			"endDate":"2011-12-01 19:16:57 MST",
			"data":{
				"time":30,
				"util":99.98
			}
		}
	]
}

Sample Response

{
	"messages":["Report cpu-util created"],
	"id":"3efe5c670be86ba8560397ff",
	"name":"cpu-util"
}

Samples

POST http://localhost/mws/rest/reports (Minimal report without datapoints)

{
	"name":"cpu-util",
	"datapointDuration":15,
	"reportSize":2
}

3.10.4 Creating Samples

The HTTP POST method is used to create Samples for Reports.

Quick Reference

POST http://localhost/mws/rest/reports

3.10.4.1 Create Samples For Report

URLs and Parameters

GET http://localhost/mws/rest/reports/<id>/samples
GET http://localhost/mws/rest/reports/<name>/samples

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Payload

To create samples for a report, simply send data and an optional timestamp to the URL above.

The payload below shows all the fields that are available during sample creation. Note that the data field can contain arbitrary JSON.

JSON Payload

{
	"timestamp":"2011-12-01 19:16:57 MST",
	"agent":"my agent",
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	}
}

Sample Response

{"messages":["1 sample(s) created for report cpu-util"]}

3.10.5 Deleting Reports

The HTTP DELETE method is used to delete Reports.

Quick Reference

DELETE http://localhost/mws/rest/reports/<id>
DELETE http://localhost/mws/rest/reports/<name>

3.10.5.1 Delete Report

URLs and Parameters

DELETE http://localhost/mws/rest/reports/<id>
DELETE http://localhost/mws/rest/reports/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the report.
name	Yes	String	-	The name of the report.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{"messages":["Report cpu-util deleted"]}

3.11 Reservations

This section describes behavior of the Reservation object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Reservation API contains the type and description of all fields in the Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/reservations	Get all reservations		Create reservation
/rest/reservations/id	Get specified reservation	Modify reservation		Release reservation

3.11.1 Getting Reservations

The HTTP GET method is used to retrieve Reservation information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/reservations/<id>

Restrictions

Only admin or user reservations are returned with this call.

3.11.1.1 Get All Reservations

URLs and Parameters

GET http://localhost/mws/rest/reservations

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/reservations?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "system.1"},
    {"id": "system.2"},
    {"id": "system.3"}
  ]
}

3.11.1.2 Get Single Reservation

URLs and Parameters

GET http://localhost/mws/rest/reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "accountingAccount": "",
  "accountingGroup": "",
  "accountingQOS": "",
  "accountingUser": "root",
  "aclRules": [  {
    "affinity": "NEUTRAL",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "RESERVATION_ID",
    "value": "system.43"
  }],
  "allocatedNodeCount": 1,
  "allocatedProcessorCount": 8,
  "allocatedTaskCount": 1,
  "allocatedNodes": [
  	{"id":"node001"}
  ],
  "comments": "",
  "creationDate": null,
  "duration": 200000000,
  "endDate": "2018-03-17 16:49:10 MDT",
  "excludeJobs":   [
    "job1",
    "job2"
  ],
  "expireDate": null,
  "flags":   [
    "REQFULL",
    "ISACTIVE",
    "ISCLOSED"
  ],
  "globalId": "",
  "hostListExpression": "",
  "id": "system.43",
  "idPrefix": "",
  "isActive": true,
  "isTracked": false,
  "label": "",
  "maxTasks": 0,
  "messages": [],
  "owner":   {
    "name": "adaptive",
    "type": "USER"
  },
  "partitionId": "switchB",
  "profile": "",
  "requirements":   {
    "architecture": "",
    "featureList":     [
      "feature1",
      "feature2"
    ],
    "featureMode": "",
    "memory": 0,
    "nodeCount": 0,
    "nodeIds": ["node001:1"],
    "os": "",
    "taskCount": 1
  },
  "reservationGroup": "",
  "resources": {"PROCS": 0},
  "startDate": "2011-11-14 20:15:50 MST",
  "statistics":   {
    "caps": 0,
    "cips": 2659.52,
    "taps": 0,
    "tips": 0
  },
  "subType": "Other",
  "taskCount": 0,
  "trigger": null,
  "triggerIds": [],
  "uniqueIndex": "",
  "variables": {}
}

3.11.2 Creating Reservations

The HTTP POST method is used to create Reservations.

Quick Reference

POST http://localhost/mws/rest/reservations

3.11.2.1 Create Reservation

URLs and Parameters

POST http://localhost/mws/rest/reservations

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when creating a Reservation, along with some sample values.

JSON Payload

{
  "accountingAccount": "",
  "accountingGroup": "",
  "accountingQOS": "",
  "accountingUser": "root",
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "GROUP",
    "value": "staff"
  }],
  "comments": "",
  "duration": 200000000,
  "endDate": "2018-03-17 16:49:10 MDT",
  "excludeJobs":   [
    "job1",
    "job2"
  ],
  "flags":   [
    "SPACEFLEX",
    "ACLOVERLAP",
    "SINGLEUSE"
  ],
  "hostListExpression": "",
  "idPrefix": "",
  "owner":   {
    "name": "adaptive",
    "type": "USER"
  },
  "partitionId": "",
  "profile": "",
  "requirements":   {
    "architecture": "",
    "featureList":     [
      "feature1",
      "feature2"
    ],
    "memory": 0,
    "os": "",
    "taskCount": 1
  },
  "reservationGroup": "",
  "resources":   {
    "PROCS": 2,
    "MEM": 1024,
    "DISK": 1024,
    "SWAP": 1024,
    "other1": 17,
    "other2": 42
  },
  "startDate": "2011-11-14 20:15:50 MST",
  "subType": "Other",
  "trigger": {
    "eventType":"START",
    "actionType":"EXEC",
    "action":"date"
  },
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Create reservation if no conflicting reservations are found.

This is equivalent to mrsvctl -c -h node01 -E.

JSON Request Body

{
  "flags":   [
    "DEDICATEDRESOURCE"
  ],
  "hostListExpression": "node01"
}

Sample Response

JSON Response for successful POST

{"id": "system.44"}

3.11.3 Modifying Reservations

The HTTP PUT method is used to modify Reservations.

Quick Reference

PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>

3.11.3.1 Modify Reservation

URLs and Parameters

PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
change-mode	Yes	String	add	Add the given variables to the variables that already exist.
			remove	Delete the given variables from the variables that already exist.
			set	Replace all existing variables with the given variables.

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when modifying a Reservation, along with some sample values.

JSON Payload for Reservation Modify

{
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["reservation 'system.43' attribute 'Variable' changed."]}

Restrictions

You can change the ACL Rules on a reservation, but not using this resource. See Create or Update ACLs.

3.11.4 Releasing Reservations

The HTTP DELETE method is used to release Reservations.

Quick Reference

DELETE http://localhost/mws/rest/reservations/<id>

3.11.4.1 Release Reservation

URLs and Parameters

DELETE http://localhost/mws/rest/reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

3.12 Services

This section describes the behavior of a Service (an interdependent collection of workflows). It is possible for a Service to be composed of multiple Services. This section describes the URLs, payloads, and responses delivered to and from Moab Web Services for each approach.

The Service API contains the type and description of all fields in the Service object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/services	Get all Services		Create Service
/rest/services/id	Get specified Service	Modify Service		Delete Service

3.12.1 Getting Service Information

The HTTP GET method is used to retrieve Service information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/services[?query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]
GET http://localhost/mws/rest/services/<id>[?[show-recursive-vc|show-vc]=true]
GET http://localhost/mws/rest/services/<name>[?[show-recursive-vc|show-vc]=true]

3.12.1.1 Get All Services

URLs and Parameters

GET http://localhost/mws/rest/services[?query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"storage","label":"exlabel"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"account":-1}
show-recursive-vc	No	true	Show extended details about the service's virtual container including nested virtual containers and nested jobs.	show-recursive-vc=true
show-vc	No	true	Show details about the service's virtual container.	show-vc=true

Sample Response

GET http://localhost:8080/mws/rest/services?query={user:"bob"}

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
        {
      "dateCreated": "2011-12-07 16:03:40 MST",
      "lastUpdated": "2011-12-07 16:03:40 MST",
      "name": "bobService.1",
      "version": 1,
      "type": "container",
      "label": null,
      "user": "bob",
      "account": "bamboo",
      "status": "A custom status message",
      "statusCode": 0,
      "includedServices":       [
        "machine0.1",
        "OSStoremachine0.1"
      ],
      "parent": null,
      "serviceTemplate":       {
        "id": "4fbd42cfc4aa4c444cc54112",
        "name": "CentosVmPlusStorage"
      },
      "attributes": {"moab":       {
        "vc": {"id": "vc56"},
        "dependencies": [        {
          "service": "machine0.1",
          "dependency": ["OSStoremachine0.1"]
        }]
      }},
      "id": "4edff0cc6852f709fa777826"
    },
        {
      "dateCreated": "2011-12-07 16:03:40 MST",
      "lastUpdated": "2011-12-07 16:03:40 MST",
      "name": "machine0.1",
      "version": 1,
      "type": "vm",
      "label": "bobs machine",
      "user": "bob",
      "account": "bamboo",
      "status": "A custom status message",
      "statusCode": 0,
      "includedServices": [],
      "parent": "bobService.1",
      "serviceTemplate":       {
        "id": "4fbd42cfc4aa4c444cc54113",
        "name": "CentosVm"
      },      
      "attributes": {"moab":       {
        "vc": {"id": "vc57"},
        "job":         {
          "id": "Moab.24",
          "template": "genericVM",
          "image": "centos5.5-stateless",
          "features": ["vlan3"],
          "variables": {"QOS": "High"},
          "resources":           {
            "mem": 2,
            "procs": 2,
            "disk": 2
          }
        }
      }},
      "id": "4edff0cc6852f709fa777827"
    },
        {
      "dateCreated": "2011-12-07 16:03:40 MST",
      "lastUpdated": "2011-12-07 16:03:40 MST",
      "name": "OSStoremachine0.1",
      "version": 1,
      "type": "storage",
      "label": null,
      "user": "bob",
      "account": "bamboo",
      "status": "A custom status message",
      "statusCode": 0,
      "includedServices": [],
      "parent": "bobService.1",
      "serviceTemplate":       {
        "id": "4fbd42cfc4aa4c444cc54114",
        "name": "OpSysStorage"
      },        
      "attributes": {"moab":       {
        "vc": {"id": "vc58"},
        "job":         {
          "id": "Moab.23",
          "template": "OSStorage",
          "resources": {"OS": 200}
        }
      }},
      "id": "4edff0cc6852f709fa777828"
    }
  ]
}

Querying Services

It is possible to query services by one or more fields based on MongoDB query syntax.

Simple Queries

To see only services that are associated with the user "bob" you can use a query such as the following:

http://localhost/mws/rest/services?query={"user":"bob"}

To see only services that are of type "vm":

http://localhost/mws/rest/services?query={"type":"vm"}

To see only bob's vm services:

http://localhost/mws/rest/services?query={"user":"bob","type":"vm"}

To see only services that are NOT associated with bob:

http://localhost/mws/rest/services?query={"user":{"$ne":"bob"}}

More Complex Queries

When the field values of the desired services are a finite set, you can use the $in operator. For example, to see services that belong to either bob, alice, or charlie, you can do the following:

http://localhost/mws/rest/services?query={"user":{"$in":["alice","bob","charlie"]}}

You can also query on embedded JSON objects within the service JSON. For example, to see services requesting 3 processors you can use:

http://localhost/mws/rest/services?query={"attributes.moab.job.resources.procs":3}

Conditional Operators

You can perform <, <=, >, >= comparisons using the $lt, $lte, $gt, $gte operators.

Operator	Comparison
$lt	<
$lte	<=
$gt	>
$gte	>=

To see services requesting < 2 processors:

http://localhost/mws/rest/services?query={"attributes.moab.job.resources.procs":{"$lt":2}}

To see services requesting >= 1024 memory:

http://localhost/mws/rest/services?query={"attributes.moab.job.resources.mem":{"$gte":1024}}

Querying Services by Date

To see all services created after Febuary 8, 2012 at 1:00 PM Mountain Standard Time (MST):

http://localhost/mws/rest/services?query={"dateCreated":{"$gt":"2012-02-08 13:00:00 MST"}}

To see services created before or on Febuary 8, 2012 at 1:00 PM Pacific Standard Time (PST):

http://localhost/mws/rest/services?query={"dateCreated":{"$lte":"2012-02-08 13:00:00 PST"}}

To see services created between 12:00 PM and 1:00 PM Eastern Standard Time (EST) on Febuary 8, 2012:

http://localhost/mws/rest/services?query={"dateCreated":{"$lte":"2012-02-08 13:00:00 EST","$gte":"2012-02-08 12:00:00 EST"}}

Querying Services by Containing Service

Services can contain other services. When a service is contained within another service, you can find out what its container is by looking at the parent field. A service that is not contained in any other service is called a top level service. If you want to see only top level services you need to query for services with a null parent.

In MongoDB syntax you query for services whose parent field have a $type of 10 (with 10 representing null). The following query shows all of bob's top level services:

http://localhost/mws/rest/services?query={"user":"bob","parent":{"$type":10}}

Once you have the top level service, you can find the direct child services:

http://localhost/mws/rest/services?query={"user":"bob","parent":"bobService.1"}

Once you have the direct children, you can find the children of those children with a similar query.

Sorting

See the sorting section of Global URL Parameters

Limiting the Number of Results

If you want to limit the number of results of services you can use the max parameter. For example, to see only 10 of bob's services:

http://localhost/mws/rest/services?query={"user":"bob"}&sort={"name":1}&max=10

To see bob's services 91-100 when sorted by name in ascending order you can combine max with offset as follows:

http://localhost/mws/rest/services?query={"user":"bob"}&sort={"name":1}&max=10&offset=90

Retrieving a Subset of Fields

To cause only certain fields to return for each service, use the fields parameter. For example, to show only the name field for each service:

http://localhost/mws/rest/services?fields=name

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {"name": "aliceService.1"},
    {"name": "machine0.1"},
    {"name": "OSStoremachine0.1"}
  ]
}

To show the name, type, and user:

http://localhost/mws/rest/services?fields=name,type,user

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {
      "name": "aliceService.1",
      "type": "container",
      "user": "alice"
    },
        {
      "name": "machine0.1",
      "type": "vm",
      "user": "alice"
    },
        {
      "name": "OSStoremachine0.1",
      "type": "storage",
      "user": "alice"
    }
  ]
}

3.12.1.2 Get Single Service

URLs and Parameters

GET http://localhost/mws/rest/services/<id>[?[show-recursive-vc|show-vc]=true]
GET http://localhost/mws/rest/services/<name>[?[show-recursive-vc|show-vc]=true]

Parameter	Required	Valid Values	Description	Example
id	Yes	String	The unique identifier of the service.
name	Yes	String	The name of the service.
show-recursive-vc	No	true	Show extended details about the service's virtual container including nested virtual containers and nested jobs.	show-recursive-vc=true
show-vc	No	true	Show details about the service's virtual container.	show-vc=true

Parameter	Required	Type	Valid Values	Description

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Samples

GET http://localhost/mws/rest/services/bobService.1?

{
  "dateCreated": "2011-12-07 16:03:40 MST",
  "lastUpdated": "2011-12-07 16:03:40 MST",
  "name": "bobService.1",
  "version": 1,
  "type": "container",
  "label": null,
  "user": "bob",
  "account": "bamboo",
  "status": "A custom status message",
  "statusCode": 0,
  "includedServices":   [
    "machine0.1",
    "OSStoremachine0.1"
  ],
  "parent": null,
  "serviceTemplate":   {
    "id": "4fbd42cfc4aa4c444cc54112",
    "name": "CentosVmPlusStorage"
  },   
  "attributes": {"moab":   {
    "vc": {"id": "vc56"},
    "dependencies": [    {
      "service": "machine0.1",
      "dependency": ["OSStoremachine0.1"]
    }]
  }},
  "id": "4edff0cc6852f709fa777826"
}

3.12.2 Creating Services

The HTTP POST method is used to create a Service.

Quick Reference

POST http://localhost/mws/rest/services

3.12.2.1 Create Service From Service Template

URLs and Parameters

POST http://localhost/mws/rest/services

Simple Case

To create a service from the template named "Rhel54VmPlusStorage":

POST http://localhost/mws/rest/services

{
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": "Rhel54VmPlusStorage",
    }
  ]
}

Alternatively you can submit:

POST http://localhost/mws/rest/services

{
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": {
        "name":"Rhel54VmPlusStorage"
      } 
    }
  ]
}

To create a service based on the service template with id "4fbd2d90c4aa4996400bsa5m"

POST http://localhost/mws/rest/services

{
  "user": "steve",
  "account": "cloud",
  "data":   [
    {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": {
        "id":"4fbd2d90c4aa4996400bsa5m"
      } 
    }
  ]
}

Extending a Service Template

If you want to create a service from a service template, but wish to extend the service template with some additional variables or generic resources, you can use the extends field. Extending a service template is also helpful when you wish to override certain values, such as the amount of memory or processors the service requires.

To extend a service template, you will need to determine the extends path for the service you wish to override. The extends path is the name of the top level service, followed by one or more localNames as described in the includedServices field. All but the last <localName> are nested containers inside the top level container. For example:

<top level service name>::<localName>[:<localName>]+

For example, suppose you want to create a new service from the "Rhel54VmPlusStorage" service template, and you want to name this new service "MyRhel54VmPlusStorage". In this example, "Rhel54VmPlusStorage" contains a service template named "SubContainer1". The localName for "SubContainer1" in the "Rhel54VmPlusStorage" includedServices field is "sc1".

Rhel54VmPlusStorage Service Template

{
   "name":"Rhel54VmPlusStorage",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"sc1",
         "serviceTemplate":"SubContainer1"
      }
   ]
}

The extends path for the instance of "SubContainer1" in your "MyRhel54VmPlusStorage" is:

MyRhel54VmPlusStorage::sc1

Let's say inside "SubContainer1" is another service template called "SubContainer2". The localName for "SubContainer2" as defined in the includedServices field for "SubContainer1" is "sc2".

SubContainer1 Service Template

{
   "name":"SubContainer1",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"sc2",
         "serviceTemplate":"SubContainer2"
      }
   ]
}

The extends path for the instance of "SubContainer2" in "MyRhel54VmPlusStorage" is:

MyRhel54VmPlusStorage::sc1:sc2

Now let's say that "SubContainer2" contains two service templates, "Rhel54Vm" and "OpsysStorage" with localNames "rvm" and "oss" respectively.

SubContainer1 Service Template

{
   "name":"SubContainer2",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"rvm",
         "serviceTemplate":"Rhel54Vm"
      },
      {
         "localName":"oss",
         "serviceTemplate":"OpSysStorage"
      }
   ]
}

The extends paths for the instances of "Rhel54VM" and "OpSysStorage" in "MyRhel54VmPlusStorage" are:

MyRhel54VmPlusStorage::sc1:sc2:rvm
MyRhel54VmPlusStorage::sc1:sc2:oss

Now that we have the extends paths for all the services that will be created from the "Rhel54VmPlusStorage" template, we can add variables to these services that were not in the service templates.

POST http://localhost/mws/rest/services

{
  "user": "steve",
  "account": "cloud",
  "data":   [
        {
      "name": "MyRhel54VmPlusStorage",
      "serviceTemplate": "Rhel54VmPlusStorage",
      "attributes": {
         "sharedData":{ "extraAttribute":"some attribute not in the Rhel54VmPlusStorage template" }
      }
    },
    {
      "name": "MyRhel54Vm",
      "extends": "MyRhel54VmPlusStorage::sc1:sc2:rvm",
      "attributes": {
          "moab": {"job": {"variables": {"extraVar": "An additional variable not in the Rhel54Vm template"}}},
          "sharedData":{ "extraAttribute":"some attribute not in the Rhel54Vm template" }          
      }    },
    {
      "name": "MyOsStorage",
      "extends": "MyRhel54VmPlusStorage::sc1:sc2:oss",
      "attributes": {
          "moab": {"job": {"variables": {"extraVar2": "An additional variable not in the OpSysStorage template"}}},
          "sharedData":{ "extraAttribute":"some attribute not in the OpSysStorage template" }          
      }
    }
  ]
}

When the "MyRhel54Vm" service is created, it will have a variable named "extraVar" even though this variable was not defined in the "Rhel54Vm" service template. Likewise, when the "MyOsStorage" service is created, it will have a variable named "extraVar2", even though no such variable was defined in the "OsStorage" service template. All three services will have an attribute named "extraAttribute" in their attributes.sharedData sections though "extraAttribute" does not appear in any service template.

Extending Services and Dependencies in a Container Service

To add a services to a container service that were not in the container's service template you first define the new services in the service request. Then you extend the includedServices field of the container with the newly defined services. This will add the new services to any that are already in the container as defined in the service template. It is only possible to add services to a container. It is not possible to remove services from a container that were defined in the container's service template.

For example, say the CentosVmPlusStorage service template contains an OpSysStorage service template and a CentosVm service template.

CentosVmPlusStorage Service Template

{
   "name":"CentosVmPlusStorage",
   "type":"container",
   …
   "includedServices":[
      {
         "localName":"oss",
         "serviceTemplate":"OpSysStorage"
      },
      {
         "localName":"cvm",
         "serviceTemplate":"CentosVm"
      }
   ]
}

To add two storage services to the service created from the CentosVmPlusStorage service template submit the following service request:

POST http://localhost/mws/rest/services

{
   "user":"bob",
   "account":"cloud",
   "data":[
      {
         "name":"BobsCentosVmPlusStorage",
         "serviceTemplate":"CentosVmPlusStorage",
         "includedServices":[
            "NewStorageToAdd1",
            "NewStorageToAdd2"
         ]
      },
      {
         "name":"NewStorageToAdd1",
         "serviceTemplate":"ExtraStorage"
      },
      {
         "name":"NewStorageToAdd2",
         "serviceTemplate":"ExtraStorage"
      }
   ]
}

The resulting service BobsCentosVmPlusStorage will contain NewStorageToAdd1, NewStorageToAdd2, a service created from the OpSysStorage template, and a service created from the CentosVm template. To add a dependency such that the CentosVm service will not be able to start until both NewStorageToAdd1 and NewStorageToAdd2 have been set up:

POST http://localhost/mws/rest/services

{
   "user":"bob",
   "account":"cloud",
   "data":[
      {
         "name":"BobsCentosVmPlusStorage",
         "serviceTemplate":"CentosVmPlusStorage",
         "includedServices":[
            "NewStorageToAdd1",
            "NewStorageToAdd2"
         ],
         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "service":"BobsCentosVm",
                     "dependency":[
                        "NewStorageToAdd1",
                        "NewStorageToAdd2"
                     ]
                  }
               ]
            }
         }
      },
      {
         "name":"BobsCentosVm",
         "extends":"CentosVmPlusStorage:cvm"
      },
      {
         "name":"NewStorageToAdd1",
         "serviceTemplate":"ExtraStorage"
      },
      {
         "name":"NewStorageToAdd2",
         "serviceTemplate":"ExtraStorage"
      }
   ]
}

Extendable Fields

You can only extend certain fields. Below is a table of fields that can be extended:

Extendable Fields	Notes
attributes.moab.dependencies	Dependencies can be added but not removed. Only applicable to containers.
attributes.moab.job.features	Features can be added but not removed.
attributes.moab.job.requestedHosts	Hosts can be added but not removed.
attributes.moab.job.resources	Including procs, mem, disk, and any generic resource.
attributes.moab.job.variables	Can either change the value of variables in the template or add new variables.
attributes.sharedData	A place for arbitrary, site-specific data.
image
includedServices	Services can be added but not removed. Only applicable to containers.
label

Sample Response

If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.

JSON Response

{"name":"MyRhel54VmPlusStorage.1"}

3.12.2.2 Create Custom Service

URLs and Parameters

POST http://localhost/mws/rest/services

Payload

POST http://localhost/mws/rest/services

{
   "user":"adaptive",
   "account":"cloud",
   "data":[
       {
         "name":"myNewService",
         "type":"container",
         "label":"My New Service",
         "includedServices":[
            "myVmContainer",
            "myNetworkStorageWorkflow",
            "myPmContainer"
         ],
         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myNetworkStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ]
            },
            "sharedData":{
               "extraAttribute":"Some arbitrary value",
               "extraAttribute2":"Another arbitrary value"
            }
         }
      },
      {
         "name":"myVmContainer",
         "type":"container",
         "includedServices":[
            "myVmWorkflow",
            "myOsStorageWorkflow"
         ],
         "attributes":{
            "moab":{
               "dependencies":[
                  {
                     "dependency":[
                        "myOsStorageWorkflow"
                     ],
                     "service":"myVmWorkflow"
                  }
               ]
            }
         }
      },
      {
         "name":"myVmWorkflow",
         "type":"vm",
         "includedServices":[         ],
         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,
                     "mem":2048,
                     "disk":80
                  },                  
                  "variables":{
                       "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericVM",
                  "requestedHosts":["i16"],
                  "features":["vlan3"]
               }
            }
         }
      },
      {
         "name":"myOsStorageWorkflow",
         "type":"storage",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "template":"OSStorage",
                  "resources":{
                     "OS":2500
                  }
               }
            }
         }
      },
      {
         "name":"myNetworkStorageWorkflow",
         "type":"storage",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "template":"extraStorage",
                  "resources":{
                     "gold":500
                  },
                  "variables":{
                     "mount":"/path/to/mount"
                  }
               }
            }
         }
      },
      {
         "name":"myPmContainer",
         "type":"container",
         "includedServices":[
            "myPmWorkflow"
         ]
      },
      {
         "name":"myPmWorkflow",
         "type":"pm",
         "includedServices":[
         ],
         "attributes":{
            "moab":{
               "job":{
                  "resources":{
                     "procs":2,           
                     "mem":2048,
                     "disk":100
                  },
                  "variables":{
                     "QOS":"Premium"
                  },
                  "image":"centos5.5-stateless",
                  "template":"genericPM"
               }
            }
         }
      }
   ]
}

Sample Response

If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.

JSON Response

{"name":"myNewService.1"}

3.12.3 Modifying Services

The HTTP PUT method is used to modify Services.

Quick Reference

PUT http://localhost/mws/rest/services/<id>
PUT http://localhost/mws/rest/services/<name>

3.12.3.1 Modify Service

URLs and Parameters

PUT http://localhost/mws/rest/services/<id>
PUT http://localhost/mws/rest/services/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Service.
name	Yes	String	-	The name of the Service .

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Example Request

Only the attributes, status, and statusCode fields may be modified in services. Note that the status field must be a valid string, and the statusCode field must be a valid number (long). Any arbitrary string and number may be used to represent the current state of the service through status and statusCode respectively.

PUT http://localhost:8080/mws/rest/services/myStorageService

{
    "status": "Done provisioning!",
    "statusCode": 200,
    "attributes": {
        "mount": "/mnt/myMount",
        "size": "2500",
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"      
        }
    }
}

The moab element of attributes cannot be modified. An error will be returned if this is attempted.

Sample Response

JSON Response

{
    "name": "myStorageService",
    "dateCreated": "2012-02-01 14:54:52 MST",
    "lastUpdated": "2012-02-01 14:54:5    2 MST",
    "type": "storage",
    "label": null,
    "user": "john",
    "account": "corp",
    "status": "Done provisioning!",
    "statusCode": 200,
    "includedServices": [],
    "parent": "myVmWithStorage",
    "attributes": {
        "moab": {
            "vc    ": {
                "id": "vc3"
            },
            "job": {
                "id": "Moab.1",
                "template": "extraStorage",
                "resources": {
                    "gold": 2500
                }
            }
        },
        "sharedData":{
            "extraAttribute":"Some arbitrary value",
            "extraAttribute2":"Another arbitrary value"        
        },
        "mount": "/mnt/myMount",
        "size": "2500"
    },
    "id": "4f29b4abe4b03c2f8e3a1a40"
}

3.12.4 Deleting Services

The HTTP DELETE method is used to delete Services.

Quick Reference

DELETE http://localhost/mws/rest/services/<id>
DELETE http://localhost/mws/rest/services/<name>

3.12.4.1 Delete Service

URLs and Parameters

DELETE http://localhost/mws/rest/services/<id>
DELETE http://localhost/mws/rest/services/<name>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the Service.
name	Yes	String	-	The name of the Service.
force-delete	No	Boolean	-	If true MWS will not check service dependencies before deleting it.

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

JSON Response

{}

3.13 Service Templates

This section describes the behavior of the Service Template object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Service Template API contains the type and description of all fields in the ServiceTemplate object. It also contains details regarding which fields are valid during PUT and POST actions.

See Create Service From Service Template to create Services from Service Templates.

The Service Template name has the following constraints:

It must only contain letters, digits, spaces, and these special characters: hyphen, period, question mark, at sign, tilde, pound sign, square brackets, angle brackets, vertical bar, equals sign, ampersand, parentheses, asterisk, curly braces, grave accent, and dollar sign.

It cannot have the same form as a MongoDB ID (24 characters of 0-9 and a-f)

It must be unique in the database.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/service-templates	Get all Service Templates		Create ServiceTemplate
/rest/service-templates/id or name	Get specified Service Template	Modify ServiceTemplate		Cancel Service Template

3.13.1 Getting Service Templates

The HTTP GET method is used to retrieve Service Template information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/service-templates/<id>
GET http://localhost/mws/rest/service-templates/<name>

3.13.1.1 Get All Service Templates

URLs and Parameters

GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]

Parameter	Required	Valid Values	Description	Example
query	No	JSON	Queries for specific results.	query={"type":"vm","createdBy":"name"}
sort	No	JSON	Sort the results. Use `1` for ascending and `-1` for descending.	sort={"name":1}

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "totalCount": 5,
  "resultCount": 5,
  "results": [
    {
      "id": "4f04a93f84ae17912ae2763e",
      "label": "Linux ESA",
      "type": "vm",
      "name": "LinEsaTemplate",
      "modified": "2011-07-04 00:00:00 MDT",
      "createdBy": "TempName",
      "includedServices": [],
      "tags": [
        "tag0",
        "tag1"
      ],
      "attributes": {
        "dependencies": {
          "service": "tid.1",
          "dependency": [
            "tid.2",
            "tid.3"
          ]
        },
        "job": {
          "image": "rhel54-stateless",
          "resources": {
            "procs": 1,
            "mem": 1024,
            "ipaddress": 1
          },
          "template": "new-vm",
          "variables": {
            "foo": "bar"
          }
        },
        "viewpoint": {
          "name": "",
          "service-description": "",
          "form": {
            "f0": "zero",
            "f1": "one"
          },
          "access": {}
        }
      }
    },
    {
      "id": "4f05dd1484ae18e002b22d92",
      "label": "Linux ESA",
      "type": "vm",
      "name": "LinEsa004",
      "modified": "2011-07-04 00:00:00 MDT",
      "createdBy": "TempName",
      "includedServices": [
        {
          "localName": "SQLServ004",
          "serviceTemplate": "LinEsaTemplate"
        }
      ],
      "tags": [
        "tag0",
        "tag1"
      ],
      "attributes": {
        "dependencies": {
          "service": "tid.1",
          "dependency": [
            "tid.2",
            "tid.3"
          ]
        },
        "job": {
          "image": "rhel54-stateless",
          "resources": {
            "procs": 1,
            "mem": 1024,
            "ipaddress": 1
          },
          "template": "new-vm",
          "variables": {
            "foo": "bar"
          }
        },
        "viewpoint": {
          "name": "",
          "service-description": "",
          "form": {
            "f0": "zero",
            "f1": "one"
          },
          "access": {}
        }
      }
    },
    {
      "id": "4f05dd7484ae18e002b22d93",
      "label": "Linux ESA",
      "type": "vm",
      "name": "R",
      "modified": "2011-07-04 00:00:00 MDT",
      "createdBy": "TempName",
      "includedServices": [
        {
          "localName": "SQLServ004",
          "serviceTemplate": "LinEsaTemplate"
        }
      ],
      "tags": [
        "tag0",
        "tag1"
      ],
      "attributes": {
        "dependencies": {
          "service": "tid.1",
          "dependency": [
            "tid.2",
            "tid.3"
          ]
        },
        "job": {
          "image": "rhel54-stateless",
          "resources": {
            "procs": 1,
            "mem": 1024,
            "ipaddress": 1
          },
          "template": "new-vm",
          "variables": {
            "foo": "bar"
          }
        },
        "viewpoint": {
          "name": "",
          "service-description": "",
          "form": {
            "f0": "zero",
            "f1": "one"
          },
          "access": {}
        }
      }
    },
    {
      "id": "4f05e41f84ae18e002b22d94",
      "label": "Linux ESA",
      "type": "vm",
      "name": "5",
      "modified": "2011-07-04 00:00:00 MDT",
      "createdBy": "TempName",
      "includedServices": [
        {
          "localName": "SQLServ004",
          "serviceTemplate": "LinEsaTemplate"
        }
      ],
      "tags": [
        "tag0",
        "tag1"
      ],
      "attributes": {
        "dependencies": {
          "service": "tid.1",
          "dependency": [
            "tid.2",
            "tid.3"
          ]
        },
        "job": {
          "image": "rhel54-stateless",
          "resources": {
            "procs": 1,
            "mem": 1024,
            "ipaddress": 1
          },
          "template": "new-vm",
          "variables": {
            "foo": "bar"
          }
        },
        "viewpoint": {
          "name": "",
          "service-description": "",
          "form": {
            "f0": "zero",
            "f1": "one"
          },
          "access": {}
        }
      }
    },
    {
      "id": "4f05e4a284ae18e002b22d95",
      "label": "Linux ESA",
      "type": "vm",
      "name": "LinEsaServ001",
      "modified": "2011-07-04 00:00:00 MDT",
      "createdBy": "TempName",
      "includedServices": [
        {
          "localName": "SQLServ004",
          "serviceTemplate": "LinEsaTemplate"
        }
      ],
      "tags": [
        "tag0",
        "tag1"
      ],
      "attributes": {
        "dependencies": {
          "service": "tid.1",
          "dependency": [
            "tid.2",
            "tid.3"
          ]
        },
        "job": {
          "image": "rhel54-stateless",
          "resources": {
            "procs": 1,
            "mem": 1024,
            "ipaddress": 1
          },
          "template": "new-vm",
          "variables": {
            "foo": "bar"
          }
        },
        "viewpoint": {
          "name": "",
          "service-description": "",
          "form": {
            "f0": "zero",
            "f1": "one"
          },
          "access": {}
        }
      }
    }
  ]
}

Querying Service Templates

It is possible to query service templates by one or more fields based on the MongoDB query syntax.

Simple Queries

To see only service templates that are associated with the user "bob", use a query like the following:

http://localhost/mws/rest/service-templates?query={"user":"bob"}

To see only service templates that are of type "vm":

http://localhost/mws/rest/service-templates?query={"type":"vm"}

To see only bob's vm service templates:

http://localhost/mws/rest/service-templates?query={"user":"bob","type":"vm"}

To see only service templates that are NOT associated with bob:

http://localhost/mws/rest/service-templates?query={"user":{"$ne":"bob"}}

More Complex Queries

When the field values of the desired service templates are a finite set, use the $in operator. For example, to see service templates that belong to either bob, alice, or charlie, do the following:

http://localhost/mws/rest/service-templates?query={"user":{"$in":["alice","bob","charlie"]}}

You can also query on embedded JSON objects within the service template JSON. For example, to see service templates requesting 3 processors, do the following:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":3}

Conditional Operators

You can perform <, <=, >, >= comparisons using the $lt, $lte, $gt, $gte operators.

Operator	Comparison
$lt	<
$lte	<=
$gt	>
$gte	>=

To see service templates requesting < 2 processors:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":{"$lt":2}}

To see service templates requesting >= 1024 memory:

http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.mem":{"$gte":1024}}

Querying Service Templates by Date

To see all service templates modified after July 4, 2011 at 10:30:00 PM Mountain Standard Time (MST):

http://localhost/mws/rest/service-templates?query={"modified":{"$gt":"2011-07-04 22:30:00 MST"}}

To see service templates modified before July 6, 2011 at 12:00 AM Pacific Standard Time (PST):

http://localhost/mws/rest/service-templates?query={"modified":{"$lt":"2011-07-06 00:00:00 PST"}}

To see service templates modified between 12:00 AM and 11:59 PM (inclusive) Eastern Standard Time (EST) on July 5, 2011

http://localhost/mws/rest/service-templates?query={"modified":{"$gte":"2011-07-05 00:00:00 EST","$lte":"2011-07-05 23:59:00 EST"}}

Sorting

See the sorting section in Global URL Parameters.

Limiting the Number of Results

To limit the size of the result set, use the max parameter. For example, to see only 10 of bob's services:

http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10

To see bob's service templates 91-100 when sorted by name in ascending order, combine max with offset as follows:

http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10&offset=90

Retrieving a Subset of Fields

To retrieve only certain fields, use the fields parameter. For example, to show only the name field for each service:

http://localhost/mws/rest/service-templates?fields=name

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {"name": "aliceService.1"},
    {"name": "machine0.1"},
    {"name": "OSStoremachine0.1"}
  ]
}

To show the name, type, and user:

http://localhost/mws/rest/service-templates?fields=name,type,user

This returns:

{
  "totalCount": 9,
  "resultCount": 3,
  "results":   [
    {
      "name": "aliceService.1",
      "type": "container",
      "user": "alice"
    },
        {
      "name": "machine0.1",
      "type": "vm",
      "user": "alice"
    },
        {
      "name": "OSStoremachine0.1",
      "type": "storage",
      "user": "alice"
    }
  ]
}

3.13.1.2 Get Single Service Template

URLs and Parameters

GET http://localhost/mws/rest/service-templates/<id>
GET http://localhost/mws/rest/service-templates/<name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Response

JSON Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "...",
	…
  }]
}

3.13.2 Creating Service Templates

The HTTP POST method is used to create Service Templates.

Quick Reference

POST http://localhost/mws/rest/service-templates

3.13.2.1 Create Service Template

URLs and Parameters

POST http://localhost/mws/rest/service-templates

See Global URL Parameters for available URL parameters.

Payload

The payload below shows some of the fields that are available when creating a Service Template, along with some sample values.

JSON Payload

{
    "attributes": {
        "moab": {
            "dependencies": [
                {
                    "dependency": [
                        "oss", 
                        "ns"
                    ], 
                    "localName": "rvm"
                }
            ], 
            "job": {
                "features": [
                    "vlan3"
                ], 
                "image": "centos5.5-stateless", 
                "requestedHosts": [
                    "i16"
                ], 
                "resources": {
                    "disk": 80, 
                    "mem": 2048, 
                    "procs": 1
                }, 
                "template": "genericVM", 
                "variables": {
                    "QOS": "Premium"
                }
            }
        }
    }, 
    "createdBy": "bob", 
    "includedServices": [
        {
            "localName": "rvm", 
            "serviceTemplate": "Rhel54Vm"
        }, 
        {
            "localName": "oss", 
            "serviceTemplate": "OpSysStorage"
        }, 
        {
            "localName": "ns", 
            "serviceTemplate": "NetworkStorage"
        }
    ], 
    "label": "Redhat Enterprise Linux 5.4 VM Plus OS and Network Storage", 
    "modified": "2011-07-04 00:00:00 MDT", 
    "name": "Rhel54VmPlusStorage", 
    "tags": [], 
    "type": "container"
}

includedServices is a key-value pair of the internal service name and the serviceTemplate. The service name is unique for each service container.

Sample Response

JSON Response for successful POST

{"id":"4f06111184ae2bbfa31fa4c7"}

If the Service Template name is not unique:

JSON Response

{
    "messages": [
        "Service template Rhel54Vm could not be created", 
        "Request has a non-unique service template name 'Rhel54Vm'", 
        "Please correct the request and try again"
    ]
}

If the Service Template included service local name is not unique to this service template:

JSON Response

{
    "messages": [
        "Service template CentOS5 could not be created", 
        "Service template request has a non-unique included service template local name ([SQLServ05])", 
        "Please correct the request and try again"
    ]
}
}

If the Service Template depends on a non-existent included service:

JSON Response

{
    "messages": [
        "Service template NSStor34 could not be created", 
        "Service template requires service template(s) [NewRhel54Vm] which do not exist", 
        "Please correct the request and try again"
    ]
}

If the Service Template depends on more than one non-existent included service:

JSON Response

{
    "messages": [
        "Service template NSStor34 could not be created", 
        "Service template requires service template(s) [NewRhel54Vm, Storage003] which do not exist", 
        "Please correct the request and try again"
    ]
}

If the Service Template name contains a colon:

JSON Response

{
{
    "messages": [
        "Service template Rhel54Vm:C could not be created", 
        "Request contains a colon (:) in the service template name 'Rhel54Vm:C'", 
        "Please correct the request and try again"
    ]
}

If the Service Template name has the same format as a MongoDB ID (Service Template ID):

JSON Response

{
    "messages": [
        "Service template 4f2049a684ae6e1d4f09bd71 could not be created", 
        "Request has a MongoDB Object ID format for the service template name '4f2049a684ae6e1d4f09bd71'", 
        "Please correct the request and try again"
    ]
}

3.13.3 Modifying Service Templates

The HTTP PUT method is used to modify Service Templates.

The modified field is not automatically updated. It will need to be changed by the user.

Quick Reference

PUT http://localhost/mws/rest/service-templates/<id>
PUT http://localhost/mws/rest/service-templates/<name>

3.13.3.1 Modify Service Template

URLs and Parameters

PUT http://localhost/mws/rest/service-templates/<id>
PUT http://localhost/mws/rest/service-templates/<name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Payload

This is similar to create, except you change the payload to what you need modified.

The payload below shows some of the fields that are available when modifying a Service Template, along with some sample values.

{
    "attributes": {
        "dependencies": {
            "dependency": [
                "tid.2",
                "tid.3"
            ],
            "service": "tid.1"
        },
        "job": {
            "image": "rhel54-stateless",
            "resources": {
                "ipaddress": 1,
                "mem": 1024,
                "procs": 1
            },
            "template": "new-vm",
            "variables": {
                "foo": "bar"
            }
        },
        "viewpoint": {
            "access": {},
            "form": {
                "f0": "zero",
                "f1": "one"
            },
            "name": "",
            "service-description": ""
        }
    },
    "createdBy": "Newname",
    "includedServices": [],
    "modified": "2011-07-04 00:00:00 MDT",
    "name": "A",
    "tags": [
        "database",
        "ele45",
        "tag56"
    ],
    "type": "RhOs"
}

Sample Response

JSON Response for successful PUT

{
    "resultCount": 1,
    "results": [
        {
            "attributes": {
                "dependencies": {
                    "dependency": [
                        "tid.2",
                        "tid.3"
                    ],
                    "service": "tid.1"
                },
                "job": {
                    "image": "rhel54-stateless",
                    "resources": {
                        "ipaddress": 1,
                        "mem": 1024,
                        "procs": 1
                    },
                    "template": "new-vm",
                    "variables": {
                        "foo": "bar"
                    }
                },
                "viewpoint": {
                    "access": {},
                    "form": {
                        "f0": "zero",
                        "f1": "one"
                    },
                    "name": "",
                    "service-description": ""
                }
            },
            "createdBy": "Newname",
            "id": "4f0746f684ae23bbd6726852",
            "includedServices": [],
            "label": "Linux ESA",
            "modified": "2011-07-04 00:00:00 MDT",
            "name": "RhOs004",
            "tags": [
                "database",
                "ele45",
                "tag56"
            ],
            "type": "RhOs"
        }
    ],
    "totalCount": 1
}

If the Service Template depends on a non-existent included service:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Service template requires service template(s) [RhOs045] which do not exist",
        "Please correct the request and try again"
    ]
}

If the Service Template depends on more than one non-existent included service:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Service template requires service template(s) [Stor45, Stor12] which do not exist",
        "Please correct the request and try again"
    ]
}

An attempt to modify the Service Template name to an existing template name:

JSON Response

{
    "messages": [
        "Service template NewR could not be updated",
        "Request has a non-unique service template name 'Stor44'"
    ]
}

3.13.4 Deleting (Canceling) Service Templates

The HTTP DELETE method is used to delete Service Templates.

Quick Reference

DELETE http://localhost/mws/rest/service-templates/<id>
DELETE http://localhost/mws/rest/service-templates/<name>

3.13.4.1 Cancel Service Template

URLs and Parameters

DELETE http://localhost/mws/rest/service-templates/<id|name>

Parameter	Required	Valid Values	Description
id	Yes	String (24 character alphanumeric)	The unique identifier of the service template.
name	Yes	String	The name of the service template.

See Global URL Parameters for available URL parameters.

Only one of id or name is required.

Response

A successful deletion

JSON Response

{}

If the Service Template ID does not exist

JSON Response

{
    "messages": [
        "Service template not found with ID '4f2049a684ae6e1d4f09bd71'"
    ]
}

If the Service Template name does not exist

JSON Response

{
    "messages": [
        "Service template not found with ID 'Stor44'"
    ]
}

If other Service Templates depend on the one being deleted

JSON Response

{
    "messages": [
        "Service template Cent5 could not be deleted", 
        "Service template 'Cent5' cannot be deleted because Service template '[Cent5]' depends on it "
    ]
}

3.14 Standing Reservations

This section describes behavior of the Standing Reservation object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Standing Reservation API contains the type and description of all fields in the Standing Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/standing-reservations	Get all standing reservations
/rest/standing-reservations/id	Get specified standing reservation

3.14.1 Getting Standing Reservations

The HTTP GET method is used to retrieve Standing Reservation information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/standing-reservations/<id>

3.14.1.1 Get All Standing Reservations

URLs and Parameters

GET http://localhost/mws/rest/standing-reservations

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/standing-reservations?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "sr1"},
    {"id": "sr2"},
    {"id": "sr3"}
  ]
}

3.14.1.2 Get Single Standing Reservation

URLs and Parameters

GET http://localhost/mws/rest/standing-reservations/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "access": "DEDICATED",
  "accounts": ["account1"],
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "EQUAL",
    "type": "USER",
    "value": "adaptive",
  }],
  "chargeAccount": "account2",
  "chargeUser": "user2",
  "classes": ["class1"],
  "clusters": ["cluster1"],
  "comment": "comment",
  "days": ["Monday"],
  "depth": 2,
  "disabled": false,
  "endTime": 86415,
  "flags": ["ALLOWJOBOVERLAP"],
  "groups": ["group1"],
  "hosts": ["host1"],
  "id": "fast",
  "jobAttributes": ["TEMPLATESAPPLIED"],
  "maxJob": 2,
  "maxTime": 0,
  "messages": ["message1"],
  "nodeFeatures": ["feature1"],
  "os": "Ubuntu 10.04.3",
  "owner":   {
    "name": "root",
    "type": "USER"
  },
  "partition": "ALL",
  "period": "DAY",
  "procLimit":   {
    "qualifier": "<=",
    "value": 5
  },
  "psLimit":   {
    "qualifier": "<=",
    "value": 60
  },
  "qoses": ["qos1"],
  "reservationAccessList": [],
  "reservationGroup": "group2",
  "resources":   {
    "PROCS": -1,
    "tapes": 1
  },
  "rollbackOffset": 43200,
  "startTime": 347040,
  "taskCount": 0,
  "tasksPerNode": 0,
  "timeLimit": -1,
  "triggers": [],
  "type": "type1",
  "users": ["user1"]
}

3.15 Virtual Containers

This section describes behavior of the Virtual Container object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Virtual Container API contains the type and description of all fields in the Virtual Container object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/vcs	Get all Virtual Containers		Create Virtual Container
/rest/vcs/id	Get specified Virtual Container	Modify Virtual Container		Destroy Virtual Container

3.15.1 Getting Virtual Containers

The HTTP GET method is used to retrieve Virtual Container information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/vcs/<id>

3.15.1.1 Get All Virtual Containers

URLs and Parameters

GET http://localhost/mws/rest/vcs

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/vcs?fields=id

{
  "totalCount": 5,
  "resultCount": 5,
  "results":   [
    {"id": "vc3"},
    {"id": "vc1"},
    {"id": "vc4"},
    {"id": "vc5"},
    {"id": "vc2"}
  ]
}

3.15.1.2 Get Single Virtual Container

URLs and Parameters

GET http://localhost/mws/rest/vcs/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "root"
  }],
  "createDate": "2011-11-15 14:01:40 MST",
  "creator": "root",
  "description": "vc2",
  "flags": ["DESTROYWHENEMPTY"],
  "id": "vc2",
  "jobs": [
    {"id":"Moab.1"}
  ],
  "nodes": [
    {"id":"node1"}
  ],
  "owner":   {
    "name": "root",
    "type": "USER"
  },
  "reservations": [
    {"id":"system.1"}
  ],
  "variables":   {
    "a": "b",
    "c": "d"
  },
  "virtualContainers": [
    {"id":"vc3"}
  ],
  "virtualMachines": [
    {"id":"vm1"}
  ]
}

3.15.2 Creating Virtual Containers

The HTTP POST method is used to create Virtual Containers.

Quick Reference

POST http://localhost/mws/rest/vcs

3.15.2.1 Create Virtual Container

URLs and Parameters

POST http://localhost/mws/rest/vcs

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when creating a Virtual Container, along with some sample values.

JSON Payload

{
  "description": "ted's vc",
  "owner":   {
    "name": "ted",
    "type": "USER"
  }
}

Sample Response

JSON Response for successful POST

{"id": "vc8"}

Restrictions

When creating a Virtual Container, the owner field is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

If ENABLEPROXY is set and you pass in the owner field as above, then the new Virtual Container will have creator and owner set to that user.

3.15.3 Modifying Virtual Containers

The HTTP PUT method is used to modify Virtual Containers.

Quick Reference

PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>

3.15.3.1 Modify Virtual Container

URLs and Parameters

PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
change-mode	Yes	String	add	Add the given objects (jobs, VMs, etc) to the objects that already exist.
			remove	Delete the given objects from the objects that already exist.
			set	Modify the attributes of the virtual container itself and not the associated objects.

See Global URL Parameters for available URL parameters.

Payload

Here are three examples of Virtual Container updates: add objects, remove objects, and update attributes.

Add objects with /rest/vcs/vc1?change-mode=add

{
  "jobs":     [
    {"id": "Moab.37"},
    {"id": "Moab.38"}
  ],
  "nodes":     [
    {"id": "node1"},
    {"id": "node2"}
  ],
  "reservations":     [
    {"id": "system.48"},
    {"id": "system.49"}
  ],
  "virtualContainers":     [
    {"id": "vc93"},
    {"id": "vc94"}
  ],
  "virtualMachines":     [
    {"id": "vm2"},
    {"id": "vm4"}
  ]
}

Remove objects with /rest/vcs/vc1?change-mode=remove

{
  "jobs":     [
    {"id": "Moab.37"},
    {"id": "Moab.38"}
  ],
  "nodes":     [
    {"id": "node1"},
    {"id": "node2"}
  ],
  "reservations":     [
    {"id": "system.48"},
    {"id": "system.49"}
  ],
  "virtualContainers":     [
    {"id": "vc93"},
    {"id": "vc94"}
  ],
  "virtualMachines":     [
    {"id": "vm2"},
    {"id": "vm4"}
  ]
}

Modify VC attributes with /rest/vcs/vc1?change-mode=set

{
  "description": "This is a new description.",
  "flags": ["HOLDJOBS"],
  "owner":     {
    "name": "ted",
    "type": "USER"
  },
  "variables":     {
    "a": "b",
    "c": "d"
  }
}

Sample Responses

These messages may not match the messages returned from Moab exactly, but they are given as examples of the structure of the responses.

JSON response for adding objects

{
  "messages":[
    "job '147' added to VC 'vc3'",
    "job 'Moab.1' added to VC 'vc3'"
  ]
}

JSON response for removing objects

{
  "messages":[
    "job '147' removed from VC 'vc3'",
    "job 'Moab.1' removed from VC 'vc3'"
  ]
}

JSON response for updating attributes

{"messages":["VC 'vc3' successfully modified"]}

Restrictions

You can change the ACL Rules on a Virtual Container, but not using this resource. See Create or Update ACLs.

3.15.4 Destroying Virtual Containers

The HTTP DELETE method is used to destroy Virtual Containers.

Quick Reference

DELETE http://localhost/mws/rest/vcs/<id>

3.15.4.1 Destroy Virtual Container

URLs and Parameters

DELETE http://localhost/mws/rest/vcs/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{}

3.16 Virtual Machines

This section describes behavior of the Virtual Machine object in Moab Web Services. It contains the URLs, payloads, and responses delivered to and from Moab Web Services.

The Virtual Machine API contains the type and description of all fields in the Virtual Machine object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource	GET	PUT	POST	DELETE
/rest/vms	Get all VMs		Create VM
/rest/vms/id	Get specified VM	Modify VM		Destroy VM
/rest/nodes/nodeId/vms	Get all VMs on a Node

3.16.1 Getting Virtual Machines

The HTTP GET method is used to retrieve Virtual Machine information. Queries for all objects and a single object are available.

Quick Reference

GET http://localhost/mws/rest/vms/<id>
GET http://localhost/mws/rest/nodes/<nodeId>/vms

3.16.1.1 Get All Virtual Machines

URLs and Parameters

GET http://localhost/mws/rest/vms

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/vms?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "vm1"},
    {"id": "vm2"},
    {"id": "vm3"}
  ]
}

3.16.1.2 Get All Virtual Machines On Node

URLs and Parameters

GET http://localhost/mws/rest/nodes/<nodeId>/vms

Parameter	Required	Type	Valid Values	Description
nodeId	Yes	String	-	The ID of the node of interest.

See Global URL Parameters for available URL parameters.

Sample Response

GET http://localhost/mws/rest/nodes/hv1/vms?fields=id

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "vm1"},
    {"id": "vm2"},
    {"id": "vm3"}
  ]
}

3.16.1.3 Get Single Virtual Machine

URLs and Parameters

GET http://localhost/mws/rest/vms/<id>

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response

{
  "aliases": [],
  "availableDisk": 1024,
  "availableMemory": 512,
  "availableProcessors": 0,
  "cpuLoad": 0.823,
  "description": "",
  "effectiveTimeToLive": 0,
  "flags":   [
    "CREATION_COMPLETED",
    "CAN_MIGRATE"
  ],
  "genericEvents": [],
  "genericMetrics": {"watts": 250},
  "id": "vm3",
  "job": {"id": "Moab.1"},
  "lastMigrationDate": null,
  "lastSubstate": "",
  "lastSubstateModificationDate": null,
  "lastUpdateDate": null,
  "migrationCount": 0,
  "networkAddress": "10.0.0.5",
  "node": {"id": "hv2"},
  "osList": [],
  "os": "stateless1",
  "powerSelectState": "NONE",
  "powerState": "ON",
  "rack": 0,
  "requestedTimeToLive": 0,
  "slot": 0,
  "startDate": null,
  "state": "BUSY",
  "substate": "",
  "totalDisk": 1024,
  "totalMemory": 512,
  "totalProcessors": 1,
  "trackingJob": {"id": "Moab.5"},
  "triggers": [],
  "variables": {}
}

3.16.2 Creating Virtual Machines

The HTTP POST method is used to create Virtual Machines.

Quick Reference

POST http://localhost/mws/rest/vms[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.16.2.1 Create Virtual Machine

URLs and Parameters

POST http://localhost/mws/rest/vms[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when creating a Virtual Machine, along with some sample values. Note that you can pass in an ID for the Virtual Machine. If you do not, Moab will choose an ID for you.

JSON Payload

{
  "totalDisk": 1024,
  "totalMemory": 512,
  "totalProcessors": 1,
  "id": "vm3",
  "node": {"id": "hv2"},
  "os": "stateless1",
  "sovereign":true,
  "storage":"os:5'c'%os:10'd'",
  "template":"CustomTemplate",
  "requestedTimeToLive":10000,
  "triggers": [],
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

JSON Response for successful POST

{"jobId": "vmcreate-25"}

The jobId in the response identifies the job that will create the virtual machine.

3.16.3 Modifying Virtual Machines

The HTTP PUT method is used to modify Virtual Machines.

Quick Reference

PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.16.3.1 Modify Virtual Machine

URLs and Parameters

PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Payload

The payload below shows all the fields that are available when modifying a Virtual Machine, along with some sample values.

JSON Payload for VM Modify

{
  "genericEvents": [],
  "genericMetrics": {"watts": 250},
  "os": "stateless1",
  "powerState": "ON",
  "state": "BUSY",
  "triggers": [],
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

JSON Response

{"messages":["successfully updated VM variables"]}

3.16.3.2 Migrate Virtual Machine

URLs and Parameters

PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows how to migrate a Virtual Machine to a node with ID "hv2".

JSON Request Body for VM Migrate to a specific node

{"node": {"id": "hv2"}}

The request body below shows how to migrate a Virtual Machine to any available node by using the destination ID of ANY, which for this operation is a reserved word.

JSON Request Body for VM Migrate to any available node

{"node": {"id": "ANY"}}

Sample Response

The HTTP response code for this operation is 202 Accepted. See the responses section for more information.

JSON Response

{"jobId": "vm-migrate1"}

Restrictions

If a migration is requested by setting the node as shown in the above examples, any other properties in the same request body will be ignored.

3.16.4 Destroying Virtual Machines

The HTTP DELETE method is used to destroy Virtual Machines.

Quick Reference

DELETE http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

3.16.4.1 Destroy Virtual Machine

URLs and Parameters

DELETE http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]

Parameter	Required	Type	Valid Values	Description
id	Yes	String	-	The unique identifier of the object.
proxy-user	No	String	-	Perform the action as this user.

See Global URL Parameters for available URL parameters.

Sample Response

JSON Response for successful DELETE

{"jobId": "vmdestroy-26"}

The jobId in the response identifies the job that will destroy the virtual machine.

<< 2API Documentation

4Reporting Framework >>

3 Resources

Table of Contents

3 Resources

3.1 Access Control Lists

Supported Methods

3.1.1 Getting ACLs

Supported Objects

3.1.2 Creating or Updating ACLs

Quick Reference

3.1.2.1 Create or Update ACL

URLs and Parameters

Payload

Sample Response

Samples

Restrictions

3.1.3 Deleting ACLs

Quick Reference

3.1.3.1 Delete ACL

URLs and Parameters

Sample Response

Restrictions

3.2 Diagnostics

Supported Methods

3.2.1 Version and Build Information

Quick Reference

URLs and Parameters

Sample Response

3.3 Images

Supported Methods

3.3.1 Getting Images

Quick Reference

3.3.1.1 Get All Images

URLs and Parameters

Sample Response

Sorting and Querying

3.3.1.2 Get Single Image

URLs and Parameters

Sample Response

3.3.2 Creating Images

Quick Reference

3.3.2.1 Create Single Image

URLs and Parameters

Request Body

Sample Response

Samples

3.3.3 Modifying Images

Quick Reference

3.3.3.1 Modify Single Image

URLs and Parameters

Example Request

Sample Response

3.3.4 Deleting Images

Quick Reference

3.3.4.1 Delete Single Image

URLs and Parameters

Sample Response

3.4 Jobs

Supported Methods

3.4.1 Getting Job Information

Quick Reference

3.4.1.1 Get All Jobs

URLs and Parameters

Sample Response

Samples

Known Issues

3.4.1.2 Get All Active Jobs

URLs and Parameters

Sample Response

3.4.1.3 Get All Complete Jobs

URLs and Parameters

Sample Response

Known Issues

3.4.1.4 Get Single Job

URLs and Parameters

Sample Response

3.4.1.5 Get Single Active Job

URLs and Parameters

Sample Response

3.4.1.6 Get Single Active Job

URLs and Parameters

Submit job based on `msub` example