EditAttachWiki Help
r14 - 18 Jul 2007 - 17:57:43 - TravisVachonYou are here: OSAF >  Projects Web  >  CosmoHome > CosmoDevelopmentHome > CosmoManagementProtocolZeroPointSix
Cosmo web server

Cosmo Management Protocol (CMP) 0.6

The Cosmo Management Protocol is a RESTful HTTP-based protocol for management of the Cosmo server. Using CMP, clients can get and put XML representations of Cosmo entities for such tasks as creating, updating and deleting user accounts in Cosmo.

Examples of tools that might use CMP:

  • Post-installation script for changing the server administrator password and email address
  • Bulk loading tool for populating the server with user accounts
  • User interface for an external user directory that synchronizes accounts in the directory and Cosmo

Protocol Specification

This document specifies version 0.6 of CMP. Version 0.3 is documented at CosmoManagementProtocolZeroPointThree.

XML Namespaces

The namespace http://osafoundation.org/cosmo/CMP is reserved for elements defined in this specification. By convention, the prefix cmp is used to denote this namespace.

URI Space

All CMP URIs occur in the /cmp URI space.

Character Encoding

All data sent by clients, including XML entity representations and usernames embedded in operation URLs, MUST be encoded in UTF-8.

HTTP Method Override

To use PUT or DELETE operations in environments that do not allow these methods, requests may include the X-HTTP-Method-Override header with a value equal to the desired HTTP method.

Example: 

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

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

Operation Preconditions

Preconditions describe the state of the server and/or of a request that must be true in order for the operation to be performed. Unless otherwise noted either in this section or for a specific operation, if a precondition is not fulfilled, the request is discarded and the response status is set to either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the requester might be able to resolve the conflict and resubmit the request.

Authentication and Access Control

All administrative CMP operations are available to existing Cosmo accounts with administrative privileges. As Cosmo uses the Basic authentication scheme, clients must provide credentials with every request. Requests for these operations without credentials are handled as per RFC 2617.

Authenticated CMP operations are available to all existing Cosmo accounts that provide valid credentials.

Anonymous CMP operations do not require authentication. In fact, if authentication credentials are provided, these requests will be rejected with 403 (Forbidden) responses.

Request Content Headers for PUT Requests

PUT requests that transfer XML representations of Cosmo entities must set the Content-Type header to text/xml. Nonconformant requests 415 (Unsupported Media Type) responses. They must also set the Content-Length header to the number of bytes in the request content; those that do not receive (411 Length Required responses).

Cosmo does not handle the Content-Transfer-Encoding, Content-Encoding, Content-Base, Content-Location, Content-MD5, and Content-Range headers. As per RFC 2616, PUT requests containing one or more of those headers are discarded and generate 501 (Not Implemented) responses.

Cosmo ignores the Content-Language request header when handling PUT requests.

Data Model

The following Cosmo entities are exposed by CMP:

User

The User entity represents a Cosmo user account. The following attributes are defined for User:

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

password
the secret token for a user account, presented as a credential when a user attempts to access the account; must be between 5 and 16 bytes; may contain any character

firstName
the given name of the user associated with the account; must be between 1 and 128 bytes; may contain any character

lastName
the surname of the user associated with the account; must be between 1 and 128 bytes; may contain any character

email
the email address of the user associated with the account; unique to the server (1:1 correspondence between user account and email address); must be between 1 and 128 bytes; must be a valid RFC2822 address

created
the date this user was created, in RFC3339 format

modified
the date this user was last modified, in RFC3339 format

administrator
whether or not this user has administrative privileges; "true" or "false"

unactivated
present if a user is unactivated, can only be sent by the server

Server Administrator User Account

Cosmo comes preloaded with a "server administrator" user account that has special semantics. This is a bootstrap user account with administrative privileges that can be used to populate the server with additional user accounts. The username of this account is root. Its username, first name and last name may not be changed, and the account may not be deleted.

Administrative Operations

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

Listing User Accounts

To list all user accounts known by Cosmo, GET the URI /cmp/users.

The response is an XML representation of a list of user accounts. The root element of the XML document is users. Contained within are user elements for each user account. An individual user element contains username, firstName, lastName, email, url, administrator and homedirUrl 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.

The homedirUrl element contains a URL that references the home directory for the user account for Journal.WebDAV and CalDAV operations. As the root user account does not have a home directory, this element is not included for that account.

Note that for security purposes, the user account's password is not included in the entity representation.

Sorting

User list sorting 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

User list paging 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 user elements for each account, the users element in the XML generated by a GET /cmp/users 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 user accounts

Example 

>>> REQUEST <<<
GET /cmp/users 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"?>
<users xmlns="http://osafoundation.org/cosmo/CMP">
  <user>
    <username>root</username>
    <firstName>Cosmo</firstName>
    <lastName>Administrator</lastName>
    <email>root@localhost</email>
    <created>2006-10-04T14:36:18-0700</created>
    <modified>2006-10-04T14:36:18-0700</modified>
    <administrator>true</administrator>
    <url>http://localhost:8080/cmp/user/root</url>
  </user>
  <user>
    <username>bcm</username>
    <firstName>Brian</firstName>
    <lastName>Moseley</lastName>
    <email>bcm@osafoundation.org</email>
    <created>2006-10-10T23:47:40-0700</created>
    <modified>2006-10-10T23:47:40-0700</modified>
    <url>http://localhost:8080/cmp/user/bcm</url>
    <administrator>true</administrator>
    <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
  </user>
  <user>
    <username>ixjonez</username>
    <firstName>Ix</firstName>
    <lastName>Jonez</lastName>
    <email>ix@maz.org</email>
    <created>2006-10-10T23:47:40-0700</created>
    <modified>2006-10-10T23:47:40-0700</modified>
    <url>http://localhost:8080/cosmo/cmp/user/ixjonez</url>
    <administrator>false</administrator>
    <homedirUrl>http://localhost:8080/cosmo/home/ixjonez</homedirUrl>
  </user>
</users>

or, if server side sorting and paging is desired: 

>>> REQUEST <<<
GET /cmp/users?ps=1&pn=2&so=ascending&st=username 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"?>
<users xmlns="http://osafoundation.org/cosmo/CMP">
  <link href="http://localhost:8080/cosmo/cmp/users?ps=1&pn=1&so=ascending&st=username" rel="first"/>
  <link href="http://localhost:8080/cosmo/cmp/users?ps=1&pn=3&so=ascending&st=username" rel="next"/>
  <link href="http://localhost:8080/cosmo/cmp/users?ps=1&pn=1&so=ascending&st=username" rel="previous"/>
  <link href="http://localhost:8080/cosmo/cmp/users?ps=1&pn=3&so=ascending&st=username" rel="last"/>
  <user>
    <username>bcm</username>
    <firstName>Brian</firstName>
    <lastName>Moseley</lastName>
    <email>bcm@osafoundation.org</email>
    <created>2006-10-10T23:47:40-0700</created>
    <modified>2006-10-10T23:47:40-0700</modified>
    <url>http://localhost:8080/cmp/user/bcm</url>
    <administrator>true</administrator>
    <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
  </user>
  <username>ixjonez</username>
    <firstName>Ix</firstName>
    <lastName>Jonez</lastName>
    <email>ix@maz.org</email>
    <created>2006-10-10T23:47:40-0700</created>
    <modified>2006-10-10T23:47:40-0700</modified>
    <url>http://localhost:8080/cosmo/cmp/user/ixjonez</url>
    <administrator>false</administrator>
    <homedirUrl>http://localhost:8080/cosmo/home/ixjonez</homedirUrl>
  </users>
  <user>
    <username>root</username>
    <firstName>Cosmo</firstName>
    <lastName>Administrator</lastName>
    <email>root@localhost</email>
    <created>2006-10-04T14:36:18-0700</created>
    <modified>2006-10-04T14:36:18-0700</modified>
    <administrator>true</administrator>
    <url>http://localhost:8080/cmp/user/root</url>
  </user>
</users>

Viewing A User Account

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

The response is an XML representation of the user account. The root element of the XML document is user. Contained within are username, firstName, lastName, email, url, administrator and homedirUrl elements. This representation is in all respects identical to the user representation described in "Listing User Accounts".

Status Codes

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

Example 

>>> REQUEST <<<
GET /cmp/user/bcm 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"?>
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <username>bcm</username>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bcm@osafoundation.org</email>
  <created>2006-10-10T23:47:40-0700</created>
  <modified>2006-10-10T23:47:40-0700</modified>
  <url>http://localhost:8080/cmp/user/bcm</url>
  <administrator>false</administrator>
  <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
</user>

Creating A User Account

To create a user account, PUT an XML representation of a User to the URI /cmp/user/<username>, where <username> is the username of the user account to be created.

Preconditions

  • The XML representation includes all attributes defined for User.

Status Codes

  • 201 (Created) - the user account was created in its entirety
  • 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was missing or invalid, or the username specified in the XML does not match the username in the request URI
  • 431 (Username In Use) - the specified user name is already used by an existing account
  • 432 (Email In Use) - the specified email address is already used by an existing account

Example 

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

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <username>ixjonez</username>
  <password>abc123</password>
  <firstName>Ix</firstName>
  <lastName>Jonez</lastName>
  <email>ix@maz.org</email>
</user>

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

Modifying A User Account

To modify a user account, PUT an XML representation of a User to the URI /cmp/user/<username>, where <username> is the username of the user account. The only necessary elements are those that represent attributes being changed, although it is harmless to include elements for non-changing attributes as well.

All exposed User attributes may be modified, except for the root user, as discussed in "Server Administrator User Account".

To change the username of an account, send the request to the URI of the existing user account but specify the new username 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 user account.

Preconditions

  • If the username is being changed, the specified username is not already in use
  • If the email address is being changed, the specified email address is not already in use

Status Codes

  • 204 (No Content) - the user account was successfully modified
  • 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was invalid, or the username specified in the XML does not match the username in the request URI
  • 431 (Username In Use) - the specified user name is already used by an existing account
  • 432 (Email In Use) - the specified email address is already used by an existing account

Example 

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

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <username>test</username>
  <password>deadbeef</password>
</user>

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

Deleting A User Account

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

The root user may not be deleted, as discussed in "Server Administrator User Account".

Multi User Deletion

To delete multiple users at the same time, POST a url-encoded list of usernames as form inputs to the URI /cmp/user/delete.

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

user=user1&user=user2&...&user=userN

is synonymous with 

"DELETE /cmp/user/user1"
"DELETE /cmp/user/user2"
...

"DELETE /cmp/user/userN"

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

Status Codes

  • 204 (No Content) - the user account was successfully deleted
  • 403 (Forbidden) - the attempt to delete the root user account was not allowed

Example 

>>> REQUEST <<<
DELETE /cmp/user/test HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

or, if DELETE is not supported: 

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

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

or, for multi-user deletion: 

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

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

user=newuser1&user=newuser2

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

Server: Apache-Coyote/1.1

Activating A User Account

To activate a user account, POST to /cmp/activate/<username>

Preconditions

  • The user must not be activated

Status Codes

  • 204 (No Content) - the user account was successfully modified
  • 404 (Not Found) - the user could not be found, or is already activated

Example 

>>> REQUEST <<<
POST /cmp/activate/ixjonez HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Getting User Count

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

Status Codes

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

Example 

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

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

14

Aggregate Space Usage Report

Recursively lists every item owned by every user, including last modified timestamp, owner username, content length in bytes (ignores dav properties and other metadata), and path.

The report can be delivered in plain text (the default) or generic XML (specified by adding /xml at the end of the request URI).

Status codes

200 OK
success

Plain text example

Note that all fields are separated by tabs (\t). 

>>> REQUEST <<<
GET /cmp/server/usage/space HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Cosmo-Version: 0.6-SNAPSHOT
Content-Type: text/plain;charset=UTF-8
Content-Length: xxx
Date: Tue, 14 Nov 2006 00:25:53 GMT

2006-11-01T19:21:24-0800        bcm     0       /bcm
2006-11-10T00:17:06-0800        bcm     15088   /bcm/pom.xml
2006-11-10T00:17:03-0800        bcm     2643    /bcm/maven.xml
2006-11-13T15:19:43-0800        tuggy   0       /tuggy

XML example 

>>> REQUEST <<<
GET /cmp/server/usage/space/xml HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Cosmo-Version: 0.6-SNAPSHOT
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx
Date: Tue, 14 Nov 2006 00:26:53 GMT

<?xml version="1.0" encoding="UTF-8"?>
<items xmlns="http://osafoundation.org/cosmo/CMP">
    <item>
        <modified>2006-11-10T00:17:03-0800</modified>
        <owner>bcm</owner>
        <size>2643</size>
        <path>/bcm/maven.xml</path>
    </item>
    <item>
        <modified>2006-11-10T00:17:06-0800</modified>
        <owner>bcm</owner>
        <size>15088</size>
        <path>/bcm/pom.xml</path>
    </item>
    <item>
        <modified>2006-11-01T19:21:24-0800</modified>
        <owner>bcm</owner>
        <size>0</size>
        <path>/bcm</path>
    </item>
    <item>
        <modified>2006-11-13T15:19:43-0800</modified>
        <owner>tuggy</owner>
        <size>0</size>
        <path>/tuggy</path>
    </item>
</items>

Individual Space Usage Report

Similar to the aggregate space usage report but only lists the items for the specified user.

Status codes

200 OK
success
403 Forbidden
the report was requested for the overlord (which does not have storage allotted for items)
404 Not Found
the report was requested for a user that could not be found in storage

Plain text example 

>>> REQUEST <<<
GET /cmp/server/usage/space/bcm HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Cosmo-Version: 0.6-SNAPSHOT
Content-Type: text/plain;charset=UTF-8
Content-Length: xxx
Date: Tue, 14 Nov 2006 00:25:53 GMT

2006-11-01T19:21:24-0800        bcm     0       /bcm
2006-11-10T00:17:06-0800        bcm     15088   /bcm/pom.xml
2006-11-10T00:17:03-0800        bcm     2643    /bcm/maven.xml

XML example 

>>> REQUEST <<<
GET /cmp/server/usage/space/bcm/xml HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Cosmo-Version: 0.6-SNAPSHOT
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx
Date: Tue, 14 Nov 2006 00:26:53 GMT

<?xml version="1.0" encoding="UTF-8"?>
<items xmlns="http://osafoundation.org/cosmo/CMP">
    <item>
        <modified>2006-11-10T00:17:03-0800</modified>
        <owner>bcm</owner>
        <size>2643</size>
        <path>/bcm/maven.xml</path>
    </item>
    <item>
        <modified>2006-11-10T00:17:06-0800</modified>
        <owner>bcm</owner>
        <size>15088</size>
        <path>/bcm/pom.xml</path>
    </item>
    <item>
        <modified>2006-11-01T19:21:24-0800</modified>
        <owner>bcm</owner>
        <size>0</size>
        <path>/bcm</path>
    </item>
</items>

Authenticated Operations

These operations are available to clients that include authentication credentials.

Viewing My Account

To view the account of the authenticated user, GET the URI /cmp/account.

The response is an XML representation of the user account. The root element of the XML document is user. Contained within are username, firstName, lastName, email, url, administrator and homedirUrl elements. This representation is in all respects identical to the user representation described in "Listing User Accounts".

Status Codes

  • 200 (OK) - the response contains an XML representation of the user account

Example 

>>> REQUEST <<<
GET /cmp/account 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"?>
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <username>bcm</username>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bcm@osafoundation.org</email>
  <created>2006-10-10T23:47:40-0700</created>
  <modified>2006-10-10T23:47:40-0700</modified>
  <url>http://localhost:8080/cmp/user/bcm</url>
  <administrator>false</administrator>
  <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
</user>

Modifying My Account

To modify the account of the authenticated user, PUT an XML representation of the User to the URI /cmp/account>. The only necessary elements are those that represent attributes being changed, although it is harmless to include elements for non-changing attributes as well. The exception to this rule is the username, which can not be changed by an end user (only by an administrator).

Preconditions

  • If administrator status is being changed, the current user must be an administrator

Status Codes

  • 204 (No Content) - the user account was successfully modified
  • 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was invalid, or the username specified in the XML does not match the username in the request URI
  • 432 (Email In Use) - the specified email address is already used by an existing account

Example 

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

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <password>deadbeef</password>
</user>

>>> RESPONSE <<<
HTTP/1.1 204 No Content
ETag: "1066573645-1134765540540"

User Service Document

To retrieve the User Service Document for the authenticated user, GET the URI /cmp/user/<username>/service.

Preconditions

  • The authenticated user must be an administrator or retrieving his own USD.

Status Codes

  • 200 (OK) - the response contains the user service document
  • 403 (Forbidden) - the authenticated user is not an administrator and requested another user's USD

Example 

>>> REQUEST <<<
GET /cmp/user/bcm/service 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'?>
<service xmlns="http://osafoundation.org/cosmo/CMP/userService">
  <username>bcm</username>
  <link title="cmp" type="text/xml" href="http://osaf.us/cosmo/cmp/user/bcm"/>
  <link title="webdav" type="text/xml" href="http://osaf.us/cosmo/dav/bcm"/>
  <link title="webdav-principal" type="text/xml" href="http://osaf.us/cosmo/dav/bcm"/>
  <link title="caldav-calendar-home" type="text/xml" href="http://osaf.us/cosmo/dav/bcm"/>
  <base title="atom" type="application/atom+xml" href="http://osaf.us/cosmo/atom"/>
  <base title="mc" type="application/eim+xml" href="http://osaf.us/cosmo/mc"/>
  <base title="pim" type="text/html" href="http://osaf.us/cosmo/pim"/>
  <base title="webcal" type="text/calendar" href="http://osaf.us/cosmo/webcal"/>
</service>

Anonymous Operations

These operations are available to clients that have not authenticated themselves to Cosmo.

Signing Up For A User Account

To sign up for a user account, PUT an XML representation of a User to the URI /cmp/signup. The response includes a Content-Location header that provides the URL for the user's home directory.

Preconditions

  • The XML representation includes all attributes defined for User except administrator
  • If an administrator tag is provided, it must have a value of false

Status Codes

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

Example 

>>> REQUEST <<<
PUT /cmp/signup HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo/CMP">
  <username>bmoseley</username>
  <password>abc123</password>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bmoseley@maz.org</email>
</user>

>>> RESPONSE <<<
HTTP/1.1 201 Created
ETag: "1066573645-1134765540540"
Content-Length: 0
Content-Location: http://localhost:8080/home/bmoseley

Implementation Notes

400 Responses

Whenever a CMP request generates a 400 (Bad Request) response, Cosmo logs a warning containing more information about the bad request. It also includes this warning as the reason phrase in the response status line (eg 400 user not root element).

Changes From Previous Versions

0.3 to 0.6

Multi-User Deletion

To delete multiple users at the same time, administrators can now POST a url-encoded list of usernames as form inputs to the URI /cmp/user/delete.

X-HTTP-Method-Override

Requests including the X-HTTP-Method-Override header will be treated as requests with a method equals to the value of this header.

Removed POST Synonymous With PUT

X-HTTP-Method-Override provides a more elegant solution to the problem these alternate syntaxes were trying to solve.

User Activation

  • POST /cmp/activate/<username> will now activate the user corresponding to <username>.
  • Representations of unactivated users will now include "read only" tag.

User Count

GET /cmp/user/count will now return the number of users currently signed up on this instance of Cosmo.

Created, Modified, and Administrator Tags

The User model now includes elements representing the date the user was created, the date the user was last modified, and an element indicating whether the user has administrator privileges.

User List Paging and Sorting

GET /cmp/users now supports query parameters pn, ps, so, and st, which specify paging and sorting criteria for the list of users to be returned. The XML response to this command with any paging or sorting parameters now includes Atom publishing collection extension style link elements with pointers to the first, last, next, and previous pages of users.

Space Usage Reports

The server now provides both aggregate and user-specific space usage reports.

User Service Documents

The server now provides an XML document that lists the URLs used to access a user's data with the various protocols and user interfaces.

0.2 to 0.3

XML Namespaces

The namespace used for XML elements defined in this specification has changed from http://osafoundation.org/cosmo, and the prefix used by convention to denote this namespace has changed from cosmo.

URI Space

The URI space for CMP operations has changed from /api.

POST Synonymous With PUT

In version 0.2, POST was not a valid method for any CMP operation.

User Attribute Syntax

In version 0.2, various user attributes were restricted to particular sets of valid characters. Version 0.3 relaxes these restrictions.

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r14 < r13 < r12 < r11 < r10 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.