4.19   Principals

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

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

Supported Methods

Resource GET PUT POST DELETE
/rest/principals Get All Principals -- Create Single Principal --
/rest/principals/<id> Get Single Principal Modify Single Principal -- Delete Single Principal
/rest/principals/<name> Get Single Principal Modify Single Principal -- Delete Single Principal

In this section:

4.19.1 Getting Principals

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

Quick Reference

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

4.19.1.A  Get All Principals

URLs and Parameters

GET https://localhost:8080/mws/rest/principals?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 principals by one or more fields based on MongoDB query syntax.

 query={"name":"Acme Principal"}
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/principals?api-version=3&fields=name,group
------------------------------------

{
  "totalCount": 2,
  "resultCount": 2,
  "results":	 [
    {
      "groups": [	{
        "name": "CN=Engineering,CN=Users,DC=corp,DC=hpc,DC=dev",
        "type": "LDAPGROUP"
      }],
	  "name": "Engineering-Principal"
    },
	{
	  "groups": [	{
        "name": "CN=Marketing,CN=Users,DC=corp,DC=hpc,DC=dev",
        "type": "LDAPGROUP"
      }],
	  "name": "Marketing-Principal"
    }
  ]
}

Sorting and Querying

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

4.19.1.B  Get Single Principal

URLs and Parameters

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

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

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/principals/principal8?api-version=3
------------------------------------

{
	  "attachedRoles": [  {
		"description": "This is a role for normal users in the Acme BU Group.",
		"id": "5033b8eae4b09cc61bedb895",
		"name": "Acme-User-Role",
		"permissions":	 [
				{
			"action": "read",
			"administrator": null,
			"description": "The permission to read all nodes",
			"id": "5033b842e4b09cc61bedb818",
			"label": "",
			"resource": "nodes",
			"resourceFilter": null,
			"type": "api",
			"version": 1
		  },
		],
		"version": 2
	  }],
	  "description": "Principal 8",
	  "groups": [  {
		"name": "CN=Engineering,CN=Users,DC=corp,DC=hpc,DC=dev",
		"type": "LDAPGROUP"
	  }],
	  "id": "5033d33fe4b018b28745fecd",
	  "name": "principal8",
	  "users":   [
		{
		  "name": "jhammon",
		  "type": "LDAP"
		},
		{
		  "name": "bjones",
		  "type": "LDAP"
		}
	  ],
	"version": 0
}

4.19.2 Creating Principals

The HTTP POST method is used to submit Principals.

Quick Reference

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

4.19.2.A  Create Single Principal

URLs and Parameters

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

See 3.3  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 attachedRoles field expects an array of Role IDs or names.

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

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

{
	"name" : "Acme-Principal",
	"attachedRoles" : [{"name":"Acme-User-Role"}],
	"description" : "A cool principal",
	"groups" : [{"name": "CN=Engineering,CN=Users,DC=corp,DC=hpc,DC=dev", "type":"LDAPGROUP"}],
	"users" : [{
		"name" : "john",
		"type" : "LDAP"
	} ]
}

Sample Response

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

4.19.3 Modifying Principals

The HTTP PUT method is used to modify Principals.

Quick Reference

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

4.19.3.A  Modify Single Principal

URLs and Parameters

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

The name of the Principal.

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

add

remove

set (default)

If add, add the given objects (ldapGroups, ldapOUs, etc.) to the objects that already exist.

If remove, delete the given objects from the objects that already exist.

If set, add the given objects (ldapGroups, ldapOUs, etc.) and remove the objects that already exist.

See 3.3  Global URL Parameters for available URL parameters.

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

The attachedRoles field expects an array of Role IDs or names.

Example Request

PUT https://locahost/mws/rest/principals/Acme-Principal?api-version=3
------------------------------------
{
	"groups" : [ {
		"name" : "CN=Marketing,CN=Users,DC=mycompany,DC=com",
		"type" : "LDAPGROUP"
	},{
		"name" : "CN=Sales,CN=Users,DC=mycompany,DC=com",
		"type" : "LDAPGROUP"
	}],
	"users" : [ {
		"name" : "jhammon",
		"type" : "LDAP"
	}]
}

The version field contains the current version of the database entry. 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 between the time that the data was retrieved and the modify request was delivered.

Sample Response

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

4.19.4 Deleting Principals

The HTTP DELETE method is used to delete Principals.

Quick Reference

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

4.19.4.A  Delete Single Principal

URLs and Parameters

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

See 3.3  Global URL Parameters for available URL parameters.

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

Sample Response

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

{}

Related Topics