4.15   Permissions

This section describes behavior of the Permissions object in MWS. It contains the URLs, request bodies, and responses delivered to and from MWS.

The 8.4.24 Fields: User's Permissions reference section contains the type and description of fields that all Permissions have in common.

Supported Methods

Resource GET PUT POST DELETE
/rest/permissions Get All Permissions -- Create Single Permission --
/rest/permissions/<id> Get Single Permission -- -- Delete Single Permission
/rest/permissions/users/<id> Get a User's Permissions -- -- --
/rest/permissions/users Get a Current User's Permissions -- -- --

In this section:

4.15.1 Getting Permissions

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

Quick Reference

GET https://localhost:8080/mws/rest/permissions?api-version=3
GET https://localhost:8080/mws/rest/permissions/<id>?api-version=3

4.15.1.A  Get All Permissions

URLs and Parameters

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

Queries for specific results.

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

 query={"type":"CUSTOM"}
sort No JSON

Sort the results. Use 1 for ascending and -1 for descending.

 sort={"name":-1}

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/permissions?api-version=3&fields=resource,action,description
------------------------------------

{
	"totalCount": 1,
	"resultCount": 1,
	"results": [{
		"resource" : "chart",
		"action" : "read",
		"description" : "The permission to view all charts."
		} ]
}

Sorting and Querying

See the sorting and querying sections of 3.3  Global URL Parameters.

4.15.1.B  Get Single Permission

URLs and Parameters

GET https://localhost:8080/mws/rest/permissions/<id>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the permission.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/permissions/<id>?api-version=3
------------------------------------

{
	"action" : "create",
	"administrator": null,
	"description" : "The permission to create all charts.",
	"id" : "50296335e4b0011b0f8394ec",
	"label" : "Create Chart",
	"resource" : "chart",
	"resourceFilter" : null,
	"type" : "custom",
	"scope" : "NONE",
	"version" : 0
}

For permissions with type "domain", scope must be GLOBAL. All other permissions should have scope NONE.

4.15.1.C  Get a User's Permissions

URLs and Parameters

GET https://localhost:8080/mws/rest/permissions/users/<name>?api-version=3
Parameter Required Type Value Description
name Yes String -- The name of the user.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/permissions/users/bob?api-version=3
------------------------------------

[
	  {
	  "action": "read",
	  "administrator": null,
	  "description": "The permission to read all charts",
	  "id": "5033b842e4b09cc61bedb818",
	  "label": "",
	  "resource": "chart",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	},
	  {
	  "action": "read",
	  "administrator": null,
	  "description": "The permission to read all pages",
	  "id": "5033b8a5e4b09cc61bedb82d",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	},
	  {
	  "action": "update",
	  "administrator": null,
	  "description": "The permission to update all pages",
	  "id": "5033b8a5e4b09cc61bedb82f",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	}
]

4.15.1.D  Get a Current User's Permissions

URLs and Parameters

GET https://localhost/mws/rest/permissions/users/?api-version=3

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost/mws/rest/permissions/users/?api-version=3
------------------------------------

[
	  {
	  "action": "read",
	  "administrator": null,
	  "description": "The permission to read all charts",
	  "id": "5033b842e4b09cc61bedb818",
	  "label": "",
	  "resource": "chart",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	},
	  {
	  "action": "read",
	  "administrator": null,
	  "description": "The permission to read all pages",
	  "id": "5033b8a5e4b09cc61bedb82d",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	},
	  {
	  "action": "update",
	  "administrator": null,
	  "description": "The permission to update all pages",
	  "id": "5033b8a5e4b09cc61bedb82f",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "scope": "NONE",
	  "version": 1
	}
]

4.15.2 Creating Permissions

The HTTP POST method is used to create Permissions.

Quick Reference

POST https://localhost:8080/mws/rest/permissions?api-version=3

4.15.2.A  Create Single Permission

URLs and Parameters

POST https://localhost:8080/mws/rest/permissions?api-version=3

See 3.3  Global URL Parameters for available URL parameters.

Request Body

The resource, action, and type are required on each permission.

Api permissions are permissions with the type 'api' and are the only permissions enforced by MWS.

Api permissions must map to a valid resource. For example, "services" is valid because there is a resource /mws/rest/services.

Api permissions must have create, read, update, or delete as the action.

The following is an example request body to create a permission:

POST https://localhost:8080/mws/rest/permissions?api-version=3
------------------------------------

{
			"resource" : "Chart",
			"action" : "read",
			"administrator" : null,
			"type" : "custom",
			"scope" : "NONE",
			"label" : "Read all charts",
			"description" : "The permissions to view all charts."
}

Sample Response

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

4.15.3 Deleting Permissions

The HTTP DELETE method is used to delete Permissions.

Quick Reference

DELETE https://localhost:8080/mws/rest/permissions/<id>?api-version=3

4.15.3.A  Delete Single Permission

URLs and Parameters

DELETE https://localhost:8080/mws/rest/permission/<id>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the permission.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

{}

Related Topics