Cosmo Feed Service: Collections

The feed service exposes a content collection as an Atom collection. The member items of a collection are listed in an Atom feed. Collections may be created and deleted, and their properties may be updated.

Representation

The attributes of a collection itself (but not its members) are represented in XHTML using the "Collection Details" microformat.

URI Templates

The template for a collection URI is /atom/collection/{uuid}[/{projection}[/{format}]][?query string]. Projections, data formats and queries are described in CosmoFeedCollectionsAndItems.

Creating a Collection

(Introduced in Cosmo 0.10)

A collection may be created by sending a POST request containing a complete XHTML representation of the collection to the user's service URI. The content type of the request must be application/xhtml+xml, and the content length must be greater than 0. The representation does not need to specify a UUID, but it MUST include a name.

The response to a creation request does not include an entity. The response includes ETag and Last-Modified headers to allow for caching of the collection document and a Location header providing the canonical feed service URL for the new collection.

The collection is created as a member of the user's home collection. The home collection is locked during the creation process. All other clients attempting to perform write operations on the home collection or its members during that time will receive a 423 Locked response.

Response Status Codes

• 201: The collection was created successfully
• 400: The request content could not be parsed or contained an invalid representation
• 409: An item with the specified UUID already exists in the server
• 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/xhtml+xml
• 423: The home collection was locked and could not be updated
• 500: Unknown server error

Examples

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

<div class="collection">
  <span class="name">Example collection</span>
  <span class="uuid">7ed1dea4-4513-4b67-9edb-29bdfaea37ac</span>
</div>

<<< RESPONSE >>>
HTTP/1.1 201 Created
Content-Length: 0
ETag: "4C7TJeMCQeCdY72n0yY155iDp7M="
Last-Modified: Tue, 10 Jul 2007 20:58:32 GMT
Location: http://example.org/chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac

Importing an icalendar collection

(Introduced in Cosmo 0.16)

A collection may be created from icalendar by sending a POST request containing the icalendar to a special import URI (/atom/user/{username}/import/{displayName}) The content type of the request must be text/calendar, and the content length must be greater than 0. The displayName for the new collection is specified on the URI and is required.

Introduced in Cosmo 1.0 is the ability to include a url in the request body instead of the actual icalendar data. The url must point to an icalendar resource.

The response to an import request does not include an entity. The response includes ETag and Last-Modified headers to allow for caching of the collection document and a Location header providing the canonical feed service URL for the new collection.

The collection is created as a member of the user's home collection. The home collection is locked during the creation process. All other clients attempting to perform write operations on the home collection or its members during that time will receive a 423 Locked response.

Response Status Codes

• 201: The collection was imported and created successfully
• 400: The request content could not be parsed or contained an invalid representation
• 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 text/calendar
• 423: The home collection was locked and could not be updated
• 500: Unknown server error

Examples

<<< REQUEST >>>
POST /chandler/atom/user/bcm/import/MyNewCollection HTTP/1.1
Content-Type: text/calendar
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

BEGIN:VCALENDAR
PRODID:-//Google Inc//Google Calendar 70.9054//EN
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:test
X-WR-TIMEZONE:America/Chicago
X-WR-CALDESC:
BEGIN:VTIMEZONE
TZID:America/Chicago
X-LIC-LOCATION:America/Chicago
BEGIN:DAYLIGHT
TZOFFSETFROM:-0600
TZOFFSETTO:-0500
TZNAME:CDT
DTSTART:19700308T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
END:DAYLIGHT
BEGIN:STANDARD
TZOFFSETFROM:-0500
TZOFFSETTO:-0600
TZNAME:CST
DTSTART:19701101T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
DTSTART;TZID=America/Chicago:20071127T140000
DTEND;TZID=America/Chicago:20071127T173000
DTSTAMP:20071130T211745Z
UID:jev0phs8mnfkuvoscrra1fh8j0@google.com
CLASS:PRIVATE
CREATED:20071130T211422Z
DESCRIPTION:a description
LAST-MODIFIED:20071130T211459Z
LOCATION:somewhere
SEQUENCE:0
STATUS:CONFIRMED
SUMMARY:a subject
TRANSP:OPAQUE
END:VEVENT
BEGIN:VTODO
UID:19970901T130000Z-123404@host.com
DTSTAMP:19970901T130000Z
DTSTART:19970415T133000Z
DUE:19970416T045959Z
SUMMARY:1996 Income Tax Preparation
CLASS:CONFIDENTIAL
CATEGORIES:FAMILY,FINANCE
PRIORITY:1
STATUS:NEEDS-ACTION
END:VTODO
END:VCALENDAR


<<< RESPONSE >>>
HTTP/1.1 201 Created
Content-Length: 0
ETag: "4C7TJeMCQeCdY72n0yY155iDp7M="
Last-Modified: Tue, 10 Jul 2007 20:58:32 GMT
Location: http://example.org/chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac

POSTing a URL to the icalendar data:

<<< REQUEST >>>
POST /chandler/atom/user/bcm/import/MyNewCollection HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
url=http://www.google.com/calendar/ical/developer-calendar%40google.com/public/basic.ics


<<< RESPONSE >>>
HTTP/1.1 201 Created
Content-Length: 0
ETag: "4C7TJeMCQeCdY72n0yY155iDp7M="
Last-Modified: Tue, 10 Jul 2007 20:58:32 GMT
Location: http://example.org/chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac

Listing the Members of a Collection

A collection feed may be returned by sending a GET request to the the collection URI.

The response includes an Atom feed document containing an item entry for each of the member note items ordered with the most recently modified item first. The content-type of the response is application/atom+xml. The response includes ETag and Last-Modified headers to enable caching.

The feed's metadata elements are populated as such for all feeds regardless of projection:

• title: collection's display name
• updated: collection's last modified timestamp
• author: username of the user
• self link: URI with rel self that can be used to retrieve the collection feed

Each entry's metadata elements are populated as follows:

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

The content of an entry is a representation of the item in the requested data format. The default data format for requests that do not specify one is dependent on the requested projection. The default projection for requests that do not specify one is basic. The content is a complete representation of the item equivalent to that returned by a request for the item entry directly with the same projection and data format.

Response Status Codes

• 200: Success
• 400: Invalid query parameters, or unsupported projection or data format
• 500: Unknown server error

Examples

<<< REQUEST >>>
GET /chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "4C7TJeMCQeCdY72n0yY155iDp7M="
Last-Modified: Tue, 10 Jul 2007 20:58:32 GMT
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:7ed1dea4-4513-4b67-9edb-29bdfaea37ac</id>
  <title type="text">Brian Moseley</title>
  <updated>2007-07-10T20:58:32.822Z</updated>
  <generator uri="http://cosmo.osafoundation.org/" version="0.7.0-SNAPSHOT">Chandler Server</generator>
  <author>
    <name>bcm</name>
  </author>
  <link rel="self" type="application/atom+xml" href="collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac" />
  <link rel="alternate" type="text/html" href="http://example.org/chandler/pim/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac" />
  <entry>
    <id>urn:uuid:33019be0-b70a-43fa-8d6a-2ecebc2e2bf2</id>
    <title type="text">Sign up for a Chandler Server account</title>
    <updated>2007-06-28T18:39:50.279Z</updated>
    <app:edited>2007-06-28T18:39:50.279Z</app:edited>
    <published>2007-06-28T18:39:50.279Z</published>
    <content type="text/html">Sign up for a Chandler Server account</content>
    <summary type="text">Sign up for a Chandler Server account</summary>
    <link rel="self" type="application/atom+xml" href="item/33019be0-b70a-43fa-8d6a-2ecebc2e2bf2" />
  </entry>
  <entry>
    <id>urn:uuid:99aa6345-d23b-4d78-ab01-81c530059072</id>
    <title type="text">Try out Chandler Server</title>
    <updated>2007-06-28T18:39:50.215Z</updated>
    <app:edited>2007-06-28T18:39:50.215Z</app:edited>
    <published>2007-06-28T18:39:50.215Z</published>
    <content type="text/html">&lt;div class="vevent">&lt;span class="summary">Try out Chandler Server&lt;/span>: &lt;abbr class="dtstart" title="2007-06-29T10:00:00PDT">Jun 29, 2007 10:00 AM PDT&lt;/abbr> to &lt;abbr class="dtend" title="2007-06-29T11:00:00PDT">Jun 29, 2007 11:00 AM PDT&lt;/abbr></content>
    <summary type="text">Try out Chandler Server: Jun 29, 2007 10:00 AM PDT to Jun 29, 2007 11:00 AM PDT</summary>
    <link rel="self" type="application/atom+xml" href="item/99aa6345-d23b-4d78-ab01-81c530059072" />
  </entry>
</feed>

Modifying a Collection

A collection's properties may be modified by sending a PUT request containing a complete XHTML representation of the collection to the collection URI (without specifying projection, format or query parameters). The content type of the request must be application/xhtml+xml, and the content length must be greater than 0. The representation defines a complete replacement for the collection's details; there is no way to represent a partial update to a collection. The representation MUST include a name.

The response to an update request does not include an entity. The response includes ETag and Last-Modified headers to allow for caching of the collection document. Since a collection's URI is based on its UUID which cannot change after the collection's creation, the response does not include a Location header.

The collection is locked during the update process. All other clients attempting to perform write operations on the collection or its members during that time will receive a 423 Locked response.

Response Status Codes

• 204: Update applied successfully
• 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/xhtml+xml
• 423: The collection was locked and could not be updated
• 500: Unknown server error

Examples

<<< REQUEST >>>
PUT /chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac HTTP/1.1
Content-Type: application/xhtml+xml
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
If-Match: "4C7TJeMCQeCdY72n0yY155iDp7M="

<div class="collection">
  <span class="name">Collection with changed name</span>
</div>

<<< RESPONSE >>>
HTTP/1.1 204 No Content
Content-Length: 0
ETag: "4C7TJeMCQeCdY72n0yY155iDp7M="
Last-Modified: Tue, 10 Jul 2007 20:58:32 GMT

Deleting a Collection

(Introduced in Cosmo 0.10)

A collection may be deleted by sending a DELETE request to the collection URI. This removes the collection from storage and disassociates every member item from it. If a member item is not associated with any other collections, the member item is also removed from storage.

The response does not include an entity.

The collection is locked during the delete process. All other clients attempting to perform write operations on the collection or its members during that time will receive a 423 Locked response.

Response Status Codes

• 204: Success
• 423: The collection was locked and could not be deleted
• 500: Unknown server error

Examples

<<< REQUEST >>>
DELETE /chandler/atom/collection/7ed1dea4-4513-4b67-9edb-29bdfaea37ac HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
If-Match: "4C7TJeMCQeCdY72n0yY155iDp7M="

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