EditAttachWiki Help
r2 - 10 Jul 2007 - 16:19:16 - BrianMoseleyYou are here: OSAF >  Projects Web  >  CosmoHome > CosmoDevelopmentHome > CosmoFeedServiceSpec > CosmoFeedPreferences

Cosmo Feed Service: Preferences

The feed service provides an Atom collection that exposes a user's preferences as Atom entries. These preferences may be manipulated using APP.

Representation

Preferences are represented in XHTML using the "Preferences" microformat.

When a client sends a representation of a preference to the server, the client may omit all Atom entry elements other than content, since the representation contains all information needed to create or update the preference.

Listing Preferences

A user's preferences feed may be returned by sending a GET request to the the URI following the template /atom/user/{username}/preferences.

The response includes an Atom feed document containing a preference entry for each of the user's preferences ordered with the most recently modified preference first. The content-type of the response is application/atom+xml. The response does not include an a ETag header since the feed does not represent an actual object stored in the server.

The feed's metadata elements are populated as such:

  • title: {username}'s Preferences
  • updated: the current point in time
  • author: username and Atom entry point URI of the user
  • self link: URI with rel self that can be used to retrieve the preferences feed

Each entry's metadata elements are populated as follows:

  • title: preference's key
  • updated: preference's last modified timestamp
  • edited: preference's last modified timestamp
  • published: preference's created timestamp
  • self link: URI with rel self that can be used to retrieve the preference entry
  • edit link: URI with rel edit that can be used to upload changes to the preference

The content of a preference entry is as described in Representation.

Response Status Codes

  • 200: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
GET /chandler/atom/user/bcm/preferences HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<<< RESPONSE >>>
HTTP/1.1 200 OK
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:xml="http://www.w3.org/XML/1998/namespace"
      xml:base="http://localhost:8080/chandler/atom/">
  <id>urn:uuid:bcm</id>
  <title type="text">bcm's Preferences</title>
  <updated>2007-07-10T17:30:47.368Z</updated>
  <generator uri="http://cosmo.osafoundation.org/" version="0.7.0-SNAPSHOT">Chandler Server</generator>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/preferences" />
  <entry>
    <id>urn:uuid:bcm-UI.Show.AccountBrowserLink</id>
    <title type="text">UI.Show.AccountBrowserLink</title>
    <updated>2007-07-10T17:30:47.373Z</updated>
    <app:edited>2007-07-10T17:30:47.373Z</app:edited>
    <published>2007-07-10T17:30:47.373Z</published>
    <link rel="self" type="application/atom+xml" href="user/bcm/preference/UI.Show.AccountBrowserLink" /> 
    <link rel="edit" type="application/atom+xml" href="user/bcm/preference/UI.Show.AccountBrowserLink" />
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <div class="preference">Preference:
           <span class="key">UI.Show.AccountBrowserLink</span> =
           <span class="value">true</span>
        </div>
      </div>
    </content>
  </entry>
</feed>

Retrieving a Preference

A preference entry may be returned by sending a GET request to the self URI found in the preference's entry within the user's preferences feed.

The response includes an Atom entry document. The content-type of the response is application/atom+xml. The response includes ETag and Last-Modified headers to allow for caching of the entry document.

The entry's meta-data elements are populated as in the preferences feed with the addition of:

  • author: username and Atom entry point URI of the user

Response Status Codes

  • 200: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
GET /chandler/atom/user/bcm/preference/UI.Show.AccountBrowserLink HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "kxVwryOzfSSBTd0LdkpoyYrNCB8="
Last-Modified: Mon, 09 Jul 2007 23:28:01 GMT
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:xml="http://www.w3.org/XML/1998/namespace"
       xml:base="http://example.org/chandler/atom/">
  <id>urn:uuid:bcm-UI.Show.AccountBrowserLink</id>
  <title type="text">UI.Show.AccountBrowserLink</title>
  <updated>2007-07-10T17:34:05.213Z</updated>
  <app:edited>2007-07-10T17:34:05.213Z</app:edited>
  <published>2007-07-10T17:34:05.213Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/preference/UI.Show.AccountBrowserLink" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/preference/UI.Show.AccountBrowserLink" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="preference">Preference:
         <span class="key">UI.Show.AccountBrowserLink</span> =
         <span class="value">true</span>
      </div>
    </div>
  </content>
</entry>

Creating a Preference

A preference may be created by sending a POST request containing an Atom entry to the preferences collection's URI. The content type of the request must be application/atom+xml, and the content length must be greater than 0. The content of the entry must be an XHTML representation of the preference. The Atom entry metadata is not stored.

The response to a creation request includes an Atom entry document describing the newly created preference. The content-type of the response is application/atom+xml. The response includes ETag and Last-Modified headers to allow for caching of the entry document. The request also includes matching Location and Content-Location headers, which tells the client that the representation enclosed in the entry document is a complete representation of the preference.

The entry's metadata elements are populated as per preference retrieval.

Response Status Codes

  • 201: The preference was successfully created
  • 409: The user already has a preference with the given key
  • 411: The request Content-Length header was not provided or was not greater than 0
  • 415: The request Content-Type header was not provided or was not application/atom+xml
  • 400: The request content could not be parsed, did not represent an Atom entry or contained an invalid representation
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
POST /chandler/atom/user/bcm/preferences HTTP/1.1
Content-Type: application/atom+xml
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="preference">Preference:
        <span class="key">test.pref.deadbeef</span> =
        <span class="value">this is the preference value</span>
      </div>
    </div>
  </content>
</entry>

<<< RESPONSE >>>
HTTP/1.1 201 Created
ETag: "TpukUDukSLLf8UtNUczUcpSFJAs="
Last-Modified: Tue, 10 Jul 2007 18:17:44 GMT
Content-Location: http://example.org/chandler/atom/user/bcm/preference/test.pref.deadbeef
Location: http://example.org/chandler/atom/user/bcm/preference/test.pref.deadbeef
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:xml="http://www.w3.org/XML/1998/namespace"
       xml:base="http://example.org/chandler/atom/">
  <id>urn:uuid:bcm-test.pref.deadbeef</id>
  <title type="text">test.pref.deadbeef</title>
  <updated>2007-07-10T18:17:44.872Z</updated>
  <app:edited>2007-07-10T18:17:44.872Z</app:edited>
  <published>2007-07-10T18:17:44.872Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/preference/test.pref.deadbeef" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/preference/test.pref.deadbeef" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="preference">Preference:
         <span class="key">test.pref.deadbeef</span> =
         <span class="value">this is the preference value</span>
      </div>
    </div>
  </content>
</entry>

Modifying a Preference

A preference may be updated by sending a PUT request containing an Atom entry to the edit URI found in the preference's entry within the user's preferences feed. The content type of the request must be application/atom+xml, and the content length must be greater than 0. The content of the entry must be a complete XHTML representation of the preference. This representation defines a complete replacement for the existing preference exposed by the edit URI; there is no way to represent partial changes to a preference.

The response includes an Atom entry document describing the updated preference. The content-type of the response is application/atom+xml. The response includes ETag and Last-Modified headers to allow for caching of the entry document. If the update caused the preference's self URI to change, the request also includes matching Location and Content-Location headers, which tells the client that the preerence is now available at a new URI and that the representation enclosed in the entry document is a complete representation of the preference.

The entry's metadata elements are populated as per preference retrieval.

Response Status Codes

  • 200: The preference was successfully modified
  • 409: The user already has a (different) preference with the given display name
  • 411: The request Content-Length header was not provided or was not greater than 0
  • 415: The request Content-Type header was not provided or was not application/atom+xml
  • 400: The request content could not be parsed, diid not represent an Atom entry or contained an invalid representation
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
PUT /chandler/atom/user/bcm/preference/test.pref.deadbeef HTTP/1.1
Content-Type: application/atom+xml
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="preference">Preference:
        <span class="key">test.pref.deadbeef.changed</span> =
        <span class="value">a new value</span>
      </div>
    </div>
  </content>
</entry>

<<< RESPONSE >>>HTTP/1.1 201 Created
ETag: "BfvizV2ZQGpmHvZe8UCMbx+NgNI="
Last-Modified: Tue, 10 Jul 2007 18:23:31 GMT
Content-Location: http://example.org/chandler/atom/user/bcm/preference/test.pref.deadbeef.changed
Location: http://example.org/chandler/atom/user/bcm/preference/test.pref.deadbeef.changed
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:xml="http://www.w3.org/XML/1998/namespace"
       xml:base="http://example.org/chandler/atom/">
  <id>urn:uuid:bcm-test.pref.deadbeef.changed</id>
  <title type="text">test.pref.deadbeef.changed</title>
  <updated>2007-07-10T18:17:44.872Z</updated>
  <app:edited>2007-07-10T18:17:44.872Z</app:edited>
  <published>2007-07-10T18:17:44.872Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/preference/test.pref.deadbeef.changed" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/preference/test.pref.deadbeef.changed" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="preference">Preference:
         <span class="key">test.pref.deadbeef.changed</span> =
         <span class="value">a new value</span>
      </div>
    </div>
  </content>
</entry>

Deleting a Preference

A preference may be deleted by sending a DELETE request to the edit URI found in the preference's entry within the user's preferences feed.

The response does not include any content.

Response Status Codes

  • 204: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
DELETE /chandler/atom/user/bcm/preference/UI.Show.AccountBrowserLink HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<<< RESPONSE >>>
HTTP/1.1 204 No Content
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r2 < r1 | 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.