EditAttachWiki Help
r4 - 10 Jul 2007 - 16:21:03 - BrianMoseleyYou are here: OSAF >  Projects Web  >  CosmoHome > CosmoDevelopmentHome > CosmoFeedServiceSpec > CosmoFeedSubscriptions

Cosmo Feed Service: Subscriptions

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

The contents of a local collection (on the same Cosmo server) referenced by a subscription are available with the same mechanism used to access published collections (see CosmoFeedCollectionsAndItems).

Representation

Subscriptions are represented in XHTML using the "Local Subscriptions" microformat.

When a client sends a representation of a subscription 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 subscription.

Since the server calculates the existence of collections and tickets, it is meaningless for clients to include existence information in a subscription representation. This information is provided by the server to allow the client to inform the user when the collection or ticket attached to a subscription has been removed by a third party.

Listing Subscriptions

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

The response includes an Atom feed document containing a subscription entry for each of the user's subscriptions ordered with the most recently modified subscription 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 Subscriptions
  • updated: the current point in time
  • author: username and Atom entry point URI of the subscriptions' owner
  • self link: URI with rel self that can be used to retrieve the subscriptions feed

Each entry's metadata elements are populated as follows:

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

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

Response Status Codes

  • 200: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
GET /chandler/atom/user/bcm/subscriptions 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://example.org/chandler/atom/">
  <id>urn:uuid:bcm-subscriptions</id>
  <title type="text">bcm's Subscriptions</title>
  <updated>2007-07-09T17:57:56.514Z</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/subscriptions" />
  <entry>
    <id>urn:uuid:bcm-test+sub</id>
    <title type="text">test sub</title>
    <updated>2007-07-09T20:19:19.731Z</updated>
    <app:edited>2007-07-09T20:19:19.731Z</app:edited>
    <published>2007-07-09T20:19:19.731Z</published>
    <link rel="self" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
    <link rel="edit" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <div class="local-subscription">Subscription:
           <span class="name">test sub</span>
          <div class="collection">Collection:
             <span class="uuid">cafebebe</span> Exists?
             <span class="exists">false</span>
          </div>
          <div class="ticket">Ticket:
             <span class="key">deadbeef</span> Exists?
             <span class="exists">false</span>
          </div>
        </div>
      </div>
    </content>
  </entry>
</feed>

Retrieving a Subscription

A subscription entry may be returned by sending a GET request to the self URI found in the subscription's entry within the user's subscriptions 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 subscriptions feed with the addition of:

  • author: username and Atom entry point URI of the subscription's owner

Response Status Codes

  • 200: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
GET /chandler/atom/user/bcm/subscription/test+sub 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-test+sub</id>
  <title type="text">test sub</title>
  <updated>2007-07-09T23:28:01.504Z</updated>
  <app:edited>2007-07-09T23:28:01.504Z</app:edited>
  <published>2007-07-09T23:28:01.504Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="local-subscription">Subscription:
         <span class="name">test sub</span>
        <div class="collection">Collection:
           <span class="uuid">cafebebe</span> Exists?
           <span class="exists">false</span>
        </div>
        <div class="ticket">Ticket:
           <span class="key">deadbeef</span> Exists?
           <span class="exists">false</span>
        </div>
      </div>
    </div>
  </content>
</entry>

Creating a Subscription

A subscription may be created by sending a POST request containing an Atom entry to the subscriptions 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 subscription. The Atom entry metadata is not stored.

The response to a creation request includes an Atom entry document describing the newly created subscription. 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 subscription.

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

Response Status Codes

  • 201: The subscription was successfully created
  • 409: The user already has a subscription 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 >>>
POST /chandler/atom/user/bcm/subscriptions 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="local-subscription">
        <span class="name">test sub</span>
        <div class="collection">
          <span class="uuid">cafebebe</span>
        </div>
        <div class="ticket">
          <span class="key">deadbeef</span>
        </div>
      </div>
    </div>
  </content>
</entry>

<<< RESPONSE >>>
HTTP/1.1 201 Created
ETag: "jSQV4wA9u0VpPKfMmEvsSHmmUC4="
Last-Modified: Mon, 09 Jul 2007 23:28:01 GMT
Content-Location: http://example.org/chandler/atom/user/bcm/subscription/test+sub
Location: http://example.org/chandler/atom/user/bcm/subscription/test+sub
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+sub</id>
  <title type="text">test sub</title>
  <updated>2007-07-09T20:07:21.921Z</updated>
  <app:edited>2007-07-09T20:07:21.921Z</app:edited>
  <published>2007-07-09T20:07:21.921Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="local-subscription">Subscription:
        <span class="name">test sub</span>
        <div class="collection">Collection:
          <span class="uuid">cafebebe</span> Exists?
          <span class="exists">false</span>
        </div>
        <div class="ticket">Ticket:
           <span class="key">deadbeef</span> Exists?
           <span class="exists">false</span>
        </div>
      </div>
    </div>
  </content>
</entry>

Modifying a Subscription

A subscription may be created by sending a PUT request containing an Atom entry to the edit URI found in the subscription's entry within the user's subscriptions 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 subscription. This representation defines a complete replacement for the existing subscription exposed by the edit URI; there is no way to represent partial changes to a subscription.

The response includes an Atom entry document describing the updated subscription. 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 subscription's self URI to change, the request also includes matching Location and Content-Location headers, which tells the client that the subscription is now available at a new URI and that the representation enclosed in the entry document is a complete representation of the subscription.

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

Response Status Codes

  • 200: The subscription was successfully modified
  • 409: The user already has a (different) subscription 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/subscription/test+sub 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="local-subscription">
        <span class="name">this is a new name</span>
        <div class="collection">
          <span class="uuid">cafebebe</span>
        </div>
        <div class="ticket">
          <span class="key">deadbeef</span>
        </div>
      </div>
    </div>
  </content>
</entry>

<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "irCOqI1zarZBNVJfApRt/6odmRM="
Last-Modified: Mon, 09 Jul 2007 23:51:46 GMT
Content-Location: http://example.org/chandler/atom/user/bcm/subscription/this+is+a+new+name
Location: http://example.org/chandler/atom/user/bcm/subscription/this+is+a+new+name
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+sub</id>
  <title type="text">test sub</title>
  <updated>2007-07-09T20:07:21.921Z</updated>
  <app:edited>2007-07-09T20:07:21.921Z</app:edited>
  <published>2007-07-09T20:07:21.921Z</published>
  <author>
    <name>bcm</name>
    <uri>user/bcm</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <link rel="edit" type="application/atom+xml" href="user/bcm/subscription/test+sub" />
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <div class="local-subscription">Subscription:
        <span class="name">test sub</span>
        <div class="collection">Collection:
          <span class="uuid">cafebebe</span> Exists?
          <span class="exists">false</span>
        </div>
        <div class="ticket">Ticket:
           <span class="key">deadbeef</span> Exists?
           <span class="exists">false</span>
        </div>
      </div>
    </div>
  </content>
</entry>

Deleting a Subscription

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

The response does not include any content.

Response Status Codes

  • 204: Success
  • 500: Unknown server error

Examples 

<<< REQUEST >>>
DELETE /chandler/atom/user/bcm/subscription/test+sub HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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