Note: The newest version of this specification, covering Chandler Server 1.1, can be found at CosmoManagementProtocolOneDotOne
Cosmo Management Protocol (CMP) 1.0
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
1.0 of CMP. Version 0.6 is documented at
CosmoManagementProtocolZeroPointSix.
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
-
locked
- whether or not this user's account is currently locked; "true" or "false"
-
subscription
- collection subscriptions can be associated to a new user by including
subscription
elements; the value of this element is the uuid of the collection to subscribe to, and the element also requires two attribtues, name
(of the subscription) and ticket
, (ticket key for the subscription).
-
preference
- extra data is associated to a user through user preferences; each preference has a
key
and value
attribute
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.
Search Queries
User list results can be restricted to only those whose first name, last name, username, or email contain a given string using the
q
query parameter.
See below for an example of the use of this functionality.
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>
</users>
or, to restrict the list of users to those with the string "org" in their first name, last name, username, or email address:
>>> REQUEST <<<
GET /cmp/users?q=org 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>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>
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
Examples
>>> 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
>>> 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>
<preference key="customAttribute1" value="value1"/>
<preference key="customAttribute2" value="value2"/>
</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.7-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.7-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.7-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.7-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
>>> 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>joewithsubscription</username>
<password>abc123</password>
<firstName>Joe</firstName>
<lastName>Schmoe</lastName>
<email>joe@osafoundation.org</email>
<subscription name="My Subscription" tickey="abcdefg">E066573645-1134765540540</subscription>
<preference key="customDataKey1" value="value1"/>
</user>
>>> RESPONSE <<<
HTTP/1.1 201 Created
ETag: "1066573645-1134765540540"
Content-Length: 0
Content-Location: http://localhost:8080/home/joewithsubscription
Password Recovery
Requesting a Recovery Token
To request a password recovery token,
POST
to the URI
/cmp/account/password/recover
. The body of the post should be a url encoded key value pair representing either the username or email address of the user account requiring password recovery. To request recovery via username, send
username=<username>
. To request recovery via email address, send
email=<emailAddress>
.
This
POST
will cause the server to send an email to the email address of the user account corresponding to the provided information. This email will contain a URL which, when visited in a web browser, will allow a user to change their password. This URL will contain a password recovery token that may be used to change a password directly using CMP.
Status Codes
- 204 (No Content) - the password recovery email was successfully sent
- 404 (Not Found) - the provided account details did not match any user account
Example
>>> REQUEST <<<
PUT /cmp/account/password/recover HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xxx
username=ixjonez
>>> RESPONSE <<<
HTTP/1.1 204 No Content
or
>>> REQUEST <<<
PUT /cmp/account/password/recover HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xxx
email=ixjonez@maz.org
>>> RESPONSE <<<
HTTP/1.1 204 No Content
Changing a Password Using a Recovery Token
Once a password recovery token has been obtained from the email sent after a
POST
to
/cmp/account/password/recover
a client may use this token to change the password of the corresponding user account. To do this,
POST
a url-encoded request of the form
password=<newPassword>
to the URI
/cmp/account/password/reset/<recoveryToken>
.
Status Codes
- 204 (No Content) - the password was successfully changed
- 404 (Not Found) - the server could not find the provided password recovery token
Example
Assuming a password recovery token a7670729-97b5-4f8d-8350-e057ac4f7e32
>>> REQUEST <<<
PUT /cmp/account/password/reset/a7670729-97b5-4f8d-8350-e057ac4f7e32 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xxx
password=lolcatz
>>> RESPONSE <<<
HTTP/1.1 204 No Content
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.16 to 1.0
User Preferences Support
User preferences can now be associated to a user on signup requests.
Subscription Support
Collection subscriptions can now be associated to a user on signup requests.
0.7 to 0.16
Subscription Support
Collection subscriptions can now be associated to a user on signup requests.
0.6 to 0.7
Password Recovery
Clients can now request a password recovery token using
POST /cmp/account/password/recover
and change a password using
POST /cmp/account/password/reset/<passwordRecoveryToken>
.
User Locking
User accounts can be locked or unlocked by including
<locked>[true|false]</locked>
in the user representation.
User Queries
GET /cmp/users
results can now be restricted to accounts with a string
<searchQuery>
in the first name, last name, username, or email address by including
q=<searchQuery>
in the query string.
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" <unactivated/> 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.