Moab Web Services > Resources > Roles

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	--	Create Single Role	--
/rest/roles/<id>	Get Single Role	Modify Single Role	--	Deleting Roles
/rest/roles/<name>	Get Single Role	Modify Single Role	--	Delete Single Role

This topic contains these sections:

Getting Roles
- Get All Roles
- Get Single Role
Creating Roles
- Create Single Role
Modifying Roles
- Modify Single Role
Deleting Roles
- Delete Single Role

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

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}

Parameter

Required

Type

Valid values

Description

Example

query

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

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.

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",
		"description" : "The permission to create all charts.",
		"id" : "5022e695e4b073f54e47c28e",
		"label" : "Create Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "read",
		"description" : "The permission to view all charts.",
		"id" : "5022e695e4b073f54e47c28f",
		"label" : "View Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "update",
		"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",
		"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
}

Creating Roles

The HTTP POST method is used to submit Roles.

Quick reference

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

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"
		}
	]
}

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

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

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

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.

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

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
------------------------------------

{}