(Click to open topic with navigation)

5.253 Roles

This section describes behavior of the Role resource in Moab Web Services. The role resource is used to control access to MWS resources based on the proxy-user. Each role is attached to a principal and contains a list of proxy-user permissions that the group can use in MWS. This section describes the URLs, request bodies, and responses delivered to and from MWS.

The Fields: Roles reference section contains the type and description of all fields in the Role object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported methods

Resource GET PUT POST DELETE
/rest/roles

Get All Roles

Get Default Permissions on Default Roles

-- Create Single Role --
/rest/roles/<id>

Get Single Role

Modify Single Role

Reset Role Permissions

-- Deleting Roles
/rest/roles/<name> Get Single Role

Modify Single Role

Reset Role Permissions

-- Delete Single Role

This topic contains these sections:

5.253.1 Getting Roles

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

Quick reference

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

5.253.1.A Get All Roles

URLs and parameters

GET http://localhost:8080/mws/rest/roles?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Valid values Description Example
query No JSON --

Queries for specific results.

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

 query={"name":"Acme-User-Role"}
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

GET http://localhost:8080/mws/rest/roles?api-version=3&fields=id,name
------------------------------------

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "Acme-User-Role"
  }]
}

Sorting and querying

See the sorting and querying sections of Global URL Parameters.

5.253.1.B Get Default Permissions on Default Roles

The defaults parameter is used to list the default permissions that are attached to the default roles.

URLs and parameters

GET http://localhost:8080/mws/rest/roles?api-version=3&defaults=true

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------
{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
        {
      "name": "HPCUser",
      "description": "Basic user, with permission to create and manage their own jobs",
      "scope": "GLOBAL",
      "permissions":       [
                {
          "action": "read",
          "administrator": false,
          "description": "Read nodes",
          "fieldPath": "*",
          "id": "5612b526e4b0b5b9bc0db341",
          "label": "read-nodes",
          "resource": "nodes",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
                {
          "action": "create",
          "administrator": false,
          "description": "Create jobs",
          "fieldPath": null,
          "id": "5612b526e4b0b5b9bc0db345",
          "label": "create-jobs",
          "resource": "jobs",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
		...
      ]
    },
        {
      "name": "HPCAdmin",
      "description": "Administrative user, with privileges for all features and jobs",
      "scope": "GLOBAL",
      "permissions":       [
                {
          "action": "read",
          "administrator": false,
          "description": "Read nodes",
          "fieldPath": "*",
          "id": "5612b526e4b0b5b9bc0db341",
          "label": "read-nodes",
          "resource": "nodes",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
                {
          "action": "update",
          "administrator": false,
          "description": "Reprovision nodes",
          "fieldPath": "operatingSystem.image",
          "id": "5612b526e4b0b5b9bc0db342",
          "label": "update-nodes-image",
          "resource": "nodes",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
		...
      ]
    }
  ]
}

5.253.1.C Get Single Role

URLs and parameters

GET http://localhost:8080/mws/rest/roles/<id>?api-version=3
GET http://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the Role.
name Yes String -- The name of the Role.

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

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/roles/Acme-User-Role?api-version=3
------------------------------------

{
	"description" : "This is a role for normal users in the Acme BU Group.",
	"id" : "5022e695e4b073f54e47c28d",
	"name" : "Acme-User-Role",
	"permissions" : [ {
		"action" : "create",
		"administrator" : null,
		"description" : "The permission to create all charts.",
		"id" : "5022e695e4b073f54e47c28e",
		"label" : "Create Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "read",
		"administrator" : null,
		"description" : "The permission to view all charts.",
		"id" : "5022e695e4b073f54e47c28f",
		"label" : "View Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "update",
		"administrator" : null,
		"description" : "The permission to modify the africa chart.",
		"id" : "5022e695e4b073f54e47c290",
		"label" : "Modify Africa Chart",
		"resource" : "chart",
		"resourceFilter" : {
			"name" : "africa"
		},
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "read",
		"administrator" : null,
		"description" : "The permissions to view John's services.",
		"id" : "5022e695e4b073f54e47c291",
		"label" : "Read John's services",
		"resource" : "services",
		"resourceFilter" : {
			"user":"john"
		},
		"type" : "api",
		"scope" : "GLOBAL",
		"version" : 0
	} ],
	"version" : 2
}

5.253.2 Creating Roles

The HTTP POST method is used to submit Roles.

Quick reference

POST http://localhost:8080/mws/rest/roles?api-version=3

5.253.2.A Create Single Role

URLs and parameters

POST http://localhost:8080/mws/rest/roles?api-version=3

See Global URL Parameters for available URL parameters.

Request body

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

The following is an example of a request body to create a role:

POST http://localhost:8080/mws/rest/roles?api-version=3
------------------------------------

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		},
		{
		"id" : "4fa197e68ca30fc605dd1df2"
		}
	]
}

Sample response

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

Samples

The permissions field only expects an array of permission IDs, as shown in the following example:

Example payload of role with 2 permissions
------------------------------------

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		}
	]
}

5.253.3 Modifying Roles

The HTTP PUT method is used to modify Roles.

Quick reference

PUT http://localhost:8080/mws/rest/roles/<id>?api-version=3
PUT http://localhost:8080/mws/rest/roles/<name>?api-version=3

5.253.3.A Modify Single Role

URLs and parameters

PUT http://localhost:8080/mws/rest/roles/<id>?api-version=3
PUT http://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the Role.
name Yes String --

The name of the Role.

The name field must contain only letters, digits, periods, dashes, and underscores.
change-mode No String

add

remove

set (default)

If add, adds the given permissions to the permissions that already exist.

If remove, deletes the given permissions from the permissions that already exist.

If set, adds the given permissions and deletes the permissions that already exist.

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

See Global URL Parameters for available URL parameters.

Example request

PUT http://locahost/mws/rest/role/Acme-User-Role?change-mode=add?api-version=3
------------------------------------

{
	"permissions":[{"id":"4fa197e68ca30fc605dd1cf0"} ]
}

Sample response

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

5.253.3.B Reset Role Permissions

The reset-permissions parameter is used to reset the permissions on a role to match the permissions of one of the default roles.

URLs and parameters

PUT http://localhost:8080/mws/rest/roles/<role>?api-version=3&reset-permissions=<default-role>
Parameter Required Type Valid values Description
role Yes String --- The role to be modified.
default-role Yes String --- The name of the default role whose permissions will be applied to the <role>.

See Global URL Parameters for available URL parameters.

Request body

JSON request body (required)
------------------------------------

{}

Sample response

{
  "description": "Basic user, with permission to create and manage their own jobs",
  "id": "5612b526e4b0b5b9bc0db389",
  "name": "HPCUser",
  "permissions":   [
        {
      "action": "read",
      "administrator": false,
      "description": "Read nodes",
      "fieldPath": "*",
      "id": "5612b526e4b0b5b9bc0db341",
      "label": "read-nodes",
      "resource": "nodes",
      "resourceFilter": null,
      "scope": "GLOBAL",
      "type": "domain",
      "version": 0
    },
        {
      "action": "create",
      "administrator": false,
      "description": "Create jobs",
      "fieldPath": null,
      "id": "5612b526e4b0b5b9bc0db345",
      "label": "create-jobs",
      "resource": "jobs",
      "resourceFilter": null,
      "scope": "GLOBAL",
      "type": "domain",
      "version": 0
    },
	...
  ],
  "scope": "GLOBAL",
  "version": 2
}

5.253.4 Deleting Roles

The HTTP DELETE method is used to delete Roles.

Quick reference

DELETE http://localhost:8080/mws/rest/roles/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/roles/<name>?api-version=3

5.253.4.A Delete Single Role

URLs and parameters

DELETE http://localhost:8080/mws/rest/roles/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the Role.
name Yes String -- The name of the Role.

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

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{}

Related Topics 

© 2016 Adaptive Computing