(Click to open topic with navigation)

5.247 Principals

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

The 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

This topic contains these sections:

5.247.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 http://localhost:8080/mws/rest/principals?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/principals/<id>?api-version=3
GET http://localhost:8080/mws/rest/principals/<name>?api-version=3

5.247.1.A Get All Principals

URLs and parameters

GET http://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 Global URL Parameters for available URL parameters.

Sample response

GET http://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=cloud,DC=dev",
        "type": "LDAPGROUP"
      }],
	  "name": "Engineering-Principal"
    },
	{
	  "groups": [	{
        "name": "CN=Marketing,CN=Users,DC=corp,DC=cloud,DC=dev",
        "type": "LDAPGROUP"
      }],
	  "name": "Marketing-Principal"
    }
  ]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

5.247.1.B Get Single Principal

URLs and parameters

GET http://localhost:8080/mws/rest/principals/<id>?api-version=3
GET http://localhost:8080/mws/rest/principals/<name>?api-version=3
Parameter Required Type Valid values 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 Global URL Parameters for available URL parameters.

Sample response

GET http://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=cloud,DC=dev",
		"type": "LDAPGROUP"
	  }],
	  "id": "5033d33fe4b018b28745fecd",
	  "name": "principal8",
	  "users":   [
		{
		  "name": "jhammon",
		  "type": "LDAP"
		},
		{
		  "name": "bjones",
		  "type": "LDAP"
		}
	  ],
	"version": 0
}

5.247.2 Creating Principals

The HTTP POST method is used to submit Principals.

Quick reference

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

5.247.2.A Create Single Principal

URLs and parameters

POST http://localhost:8080/mws/rest/principals?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 attachedRoles field expects an array of Role IDs or names:

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

POST http://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=cloud,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.

5.247.3 Modifying Principals

The HTTP PUT method is used to modify Principals.

Quick reference

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

5.247.3.A Modify Single Principal

URLs and parameters

PUT http://localhost:8080/mws/rest/principals/<id>?api-version=3
PUT http://localhost:8080/mws/rest/principals/<name>?api-version=3
Parameter Required Type Valid values 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 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 http://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.

5.247.4 Deleting Principals

The HTTP DELETE method is used to delete Principals.

Quick reference

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

5.247.4.A Delete Single Principal

URLs and parameters

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

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

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

{}

Related Topics 

© 2016 Adaptive Computing