Cosmo Management Protocol (CMP) - Group Management

---

---

Data Model

The following Cosmo entities are exposed by CMP:

Group

The Group entity represents a Cosmo group account. The following attributes are defined for Group:

groupname

the unique identifier for a user account, presented as a credential when an a user attempts to access the account; must be between 3 and 32 bytes; may contain any non-whitespace character as well as ' '

created

the date this group was created, in RFC3339 format

modified

the date this group was last modified, in RFC3339 format

Administrative Operations

These operations are available to clients that include authentication credentials linked to an administrative account.

Listing Group Accounts

To list all group accounts known by Cosmo, GET the URI /cmp/groups.

The response is an XML representation of a list of group accounts. The root element of the XML document is groups. Contained within are group elements for each group account. An individual group element contains groupname and =url=elements.

The url element contains a URL that can be used to access the user account directly, enabling the CMP view, modify and delete operations on it.

Sorting

Group list sorting works the same way as User list paging and can be specified with two parameters in the URL query string:

st - sort type

user attribute to sort on

Legal Values:

[username | name | email | administrator | created | modified]

so - sort order

order in which to return results

Legal Values:

[ascending | descending]

Paging

Group list paging works the same way as User list paging and can be specified with two parameters in the URL query string:

ps - page size

maximum number of users to retrieve

Legal Values:

Integers >= 1

pn - page number

given page size and sorting parameters, which page of users to return

Legal Values:

Integers >= 1

Atom Collection Paging Extensions

In addition to group elements for each account, the groups element in the XML generated by a GET /cmp/groups request with any paging or sorting parameters will contain link elements with href attributes pointing to the first, last, next, or previous pages of users, as specified in the Atom Collection Paging extensions.

Status Codes

• 200 (OK) - the response contains an XML listing of group accounts

Example

>>> REQUEST <<<
GET /cmp/groups HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<groups xmlns="http://osafoundation.org/cosmo/CMP">
  <group>
    <groupname>testgroup</groupname>
    <created>2006-10-04T14:36:18-0700</created>
    <modified>2006-10-04T14:36:18-0700</modified>
    <url>http://localhost:8080/cmp/group/testgroup</url>
  </group>
  <group>
    <groupname>testgroup1</groupname>
    <created>2006-10-04T14:36:18-0700</created>
    <modified>2006-10-04T14:36:18-0700</modified>
    <url>http://localhost:8080/cmp/group/testgroup1</url>
  </group>
  <group>
    <groupname>testgroup2</groupname>
    <created>2006-10-04T14:36:18-0700</created>
    <modified>2006-10-04T14:36:18-0700</modified>
    <url>http://localhost:8080/cmp/group/testgroup2</url>
  </group>
</groups>

Viewing A Group Account

To view an individual group account, GET the URI /cmp/group/<groupname>, where <groupname> is the groupname of the group account.

The response is an XML representation of the group account excluding the members in that group. The root element of the XML document is group. Contained within are groupname and url elements. This representation is in all respects identical to the group representation described in "Listing group Accounts".

Status Codes

• 200 (OK) - the response contains an XML representation of the group account
• 404 (Not Found) - the specified group account does not exist

Example

>>> REQUEST <<<
GET /cmp/group/testgroup HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
ETag: "1066573645-1134765540540"
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<group xmlns="http://osafoundation.org/cosmo/CMP">
  <groupname>bcm</groupname>
  <created>2006-10-10T23:47:40-0700</created>
  <modified>2006-10-10T23:47:40-0700</modified>
  <url>http://localhost:8080/cmp/group/testgroup</url>
</group>

Viewing members of a particular group account

To view members of an individual group account, GET the URI /cmp/members/<groupname>, where <groupname> is the groupname of the group account.

The response is an XML representation of members in the given group account. The root element of the XML document is members. Contained within are group and user elements.

Status Codes

• 200 (OK) - the response contains an XML representation of members in a group.
• 404 (Not Found) - the specified group account does not exist

Example

>>> REQUEST <<<
GET /cmp/members/testgroup HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
ETag: "1066573645-1134765540540"
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<members xmlns="http://osafoundation.org/cosmo/CMP">
 <user>bcm</user>
 <group>group1</group>
</members>

Creating A Group Account

To create a group account, PUT an XML representation of a Group to the URI /cmp/group/<groupname>, where <groupname> is the groupname of the group account to be created.

Preconditions

• The XML representation must have a single attribute groupname.

Status Codes

• 201 (Created) - the group account was created in its entirety
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was missing or invalid, or the groupname specified in the XML does not match the groupname in the request URI
• 431 (Groupname In Use) - the specified groupname is already used by an existing account

Example

>>> REQUEST <<<
PUT /cmp/group/testgroup HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="utf-8" ?> 
<group xmlns="http://osafoundation.org/cosmo/CMP">
  <groupname>ixjonez</groupname>
</group>

>>> RESPONSE <<<
HTTP/1.1 201 Created
ETag: "1066573645-1134765540540"
Content-Length: 0

Adding members to a Group Account

To add members to a group account, POST a url-encoded list of usernames or groupnames as form inputs to the URI /cmp/group/<groupname>, where <groupname> is the groupname of the group account to be modified.

For example, POST /cmp/group/<groupname> with a message body like

group=group1&...&group=groupN&user=user1&...&user=userN

All the existing members of this group will be deleted and new members posted will be the only members of this group.

Status Codes

• 204 (No Content) - the group members were added successfully

Example

>>> REQUEST <<<
POST /cosmo/cmp/members/testgroup HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

group=existinggroup1&group=existinggroup2&user=bcm

>>> RESPONSE <<<
HTTP/1.1 204 No Content

Server: Apache-Coyote/1.1

Modifying A Group Account

To change the groupname of an account, send the request to the URI of the existing group account but specify the new groupname in the uploaded XML representation. When this happens, the response will include the Content-Location header; the value is a URL that MUST be used to for further access to the group account.

Preconditions

• If the groupname is being changed, the specified groupname is not already in use

Status Codes

• 204 (No Content) - the group account was successfully modified
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was invalid, or the groupname specified in the XML does not match the groupname in the request URI
• 431 (Groupname In Use) - the specified groupname is already used by an existing group account.

Example

>>> REQUEST <<<
PUT /cmp/group/testgroup HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="utf-8" ?> 
<group xmlns="http://osafoundation.org/cosmo/CMP">
  <groupname>newgroup</groupname>
</group>

>>> RESPONSE <<<
HTTP/1.1 204 No Content
ETag: "1066573645-1134765540540"
Content-Location: http://localhost:8080/cmp/user/test

Deleting A Group Account

To delete a user account, DELETE the URI /cmp/group/<groupname>, where <groupname> is the groupname of the group account.

Multi Group Deletion

To delete multiple groups at the same time, POST a url-encoded list of groupnames as form inputs to the URI /cmp/group/delete.

For example, POST /cmp/group/delete with a message body like

group=group1&group=group2&...&group=groupN

is synonymous with

"DELETE /cmp/group/group1"
"DELETE /cmp/group/group2"
...

"DELETE /cmp/group/groupN" 

Note that if one deletion fails, all deletions will fail.

Status Codes

• 204 (No Content) - the user account was successfully deleted

Example

>>> REQUEST <<<
DELETE /cmp/group/testgroup HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 204 No Content

or, if DELETE is not supported:

>>> REQUEST <<<
POST /cmp/group/testgroup HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-HTTP-Method-Override: DELETE

>>> RESPONSE <<<
HTTP/1.1 204 No Content

or, for multi-group deletion:

>>> REQUEST <<<
POST /cosmo/cmp/group/delete HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

group=newgroup1&group=newgroup2

>>> RESPONSE <<<
HTTP/1.1 204 No Content

Server: Apache-Coyote/1.1

Getting Group Count

To get the total number of group accounts on this instance of Cosmo, GET /cmp/groups/count.

Status Codes

• 200 (OK) - the response includes the number of user accounts on this instance of Cosmo.

Example

>>> REQUEST <<<
GET /cmp/groups/count HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: xxx

2

---

VinubalajiGopal - 01 Feb 2007