Cosmo Feed Service: Items
The feed service exposes note items as entries within Atom collections. These entries may be manipulated using APP.
Representation
The feed service provides and accepts item entry content in EIM-JSON and EIMML (see
CosmoFeedCollectionsAndItems for details). When a client sends a representation of an item to the server, the client must specify the type of the entry content as one or the other of these formats' media types. The client may omit all Atom entry elements other than content, since either representation contains all information needed to create or update the item.
Listing Items
See
CosmoFeedCollections for a description of listing the member items of a collection in a collection feed.
Retrieving an Item
An
item entry may be returned by sending a
GET request to the
self URI found in the item's entry within a collection feed. The URI may include projection and format identifiers and query parameters (see
CosmoFeedCollectionsAndItems for more information). The template for an item URI is
/atom/item/{uuid}[/{projection}[/{format}]][?{query string}].
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 collection feed with the addition of:
- author: username of the user and, for projections other than basic, the user's Atom entry point URI
Response Status Codes
- 200: Success
- 400: Unsupported projection or data format
- 500: Unknown server error
Examples
<<< REQUEST >>>
GET /chandler/atom/item/96e0364e-db7d-4250-98a2-99ef4f402c0b HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "qC34DI11NJLl9/lCZRf+rlZBy04="
Last-Modified: Thu, 12 Jul 2007 18:53:58 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:96e0364e-db7d-4250-98a2-99ef4f402c0b</id>
<title type="text">Welcome to Chandler Server</title>
<updated>2007-07-12T18:53:58.001Z</updated>
<app:edited>2007-07-12T18:53:58.001Z</app:edited>
<published>2007-07-12T18:53:58.001Z</published>
<author>
<name>bcm</name>
</author>
<content type="html"><div class="vevent"><span class="summary">Welcome to Chandler Server</span>: <abbr class="dtstart" title="2007-07-12T11:00:00PDT">Jul 12, 2007 11:00 AM PDT</abbr> to <abbr class="dtend" title="2007-07-12T12:00:00PDT">Jul 12, 2007 12:00 PM PDT</abbr></content>
<summary type="text">Welcome to Chandler Server: Jul 12, 2007 11:00 AM PDT to Jul 12, 2007 12:00 PM PDT</summary>
<link rel="self" type="application/atom+xml" href="item/96e0364e-db7d-4250-98a2-99ef4f402c0b" />
</entry>
Creating an Item
An item may be created by sending a
POST request containing an Atom entry to the URI of the collection in which the item is to be added. 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 EIM-JSON or EIMML representation of the item. The Atom entry metadata is not stored.
The response to a creation request includes an Atom entry document describing the newly created item. 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 item. The entry's metadata elements are populated as per item retrieval.
The collection in which the item is being created is locked during the creation process. All other clients attempting to perform write operations on the collection or its children during that time will receive a
423 Locked response.
Response Status Codes
- 201: The item was successfully created
- 400: The request content could not be parsed, did not represent an Atom entry or contained an invalid representation
- 409: An item with the specified UUID already exists in the server, or the uploaded item contained an iCalendar UID that is in use by an item already in the collection
- 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
- 423: The collection was locked and could not be updated
- 500: Unknown server error
Examples
<<< REQUEST >>>
POST /chandler/atom/collection/5658ce1e-491b-44ba-a65f-875571cfa939 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="application/eim+json">{"uuid":"8ed8bd32-18f1-11dc-e1d4-d2641e3508a6","records":{"item":{"ns":"http://osafoundation.org/eim/item/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"title":["text","Recurring daily event"],"triage":["text","200 -1181658614.11 1"],"hasBeenSent":["integer","0"],"needsReply":["integer","0"],"createdOn":["decimal","1181658614"]}},"modby":{"ns":"http://osafoundation.org/eim/modifiedBy/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"],"userid":["text","bcm"],"timestamp":["decimal","1181658622"],"action":["integer","500"]}},"note":{"ns":"http://osafoundation.org/eim/note/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"body":["clob",null],"icalUid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]}},"event":{"ns":"http://osafoundation.org/eim/event/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"dtstart":["text",";VALUE=DATE-TIME;TZID=America/Los_Angeles:20070612T121500"],"duration":["text","PT1H"],"location":["text",null],"rrule":["text","FREQ=DAILY;UNTIL=20070616T065900Z"],"exrule":["text",null],"rdate":["text",null],"exdate":["text",null],"status":["text","CONFIRMED"]}},"displayAlarm":{"ns":"http://osafoundation.org/eim/displayAlarm/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"description":["text",null],"trigger":["text",null],"duration":["text",null],"repeat":["integer",null]}}}}</content>
</entry>
<<< RESPONSE >>>
HTTP/1.1 201 Created
ETag: "pVZ8bTMaEK+fAFQRF4M5wCXuav0="
Last-Modified: Fri, 13 Jul 2007 20:59:13 GMT
Content-Location: http://example.org/chandler/atom/item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6/full/eim-json
Location: http://example.org/chandler/atom/item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6/full/eim-json
Content-Type: application/atom+xml
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns:app="http://www.w3.org/2007/app"
xmlns="http://www.w3.org/2005/Atom"
xml:base="http://example.org/chandler/atom/">
<id>urn:uuid:8ed8bd32-18f1-11dc-e1d4-d2641e3508a6</id>
<title type="text">Recurring daily event</title>
<updated>2007-07-13T21:02:58.047Z</updated>
<app:edited>2007-07-13T21:02:58.047Z</app:edited>
<published>2007-07-13T21:02:58.047Z</published>
<author>
<name>bcm</name>
</author>
<content type="html"><div class="vevent"><span class="summary">Recurring daily event</span>: <abbr class="dtstart" title="2007-06-12T12:15:00PDT">Jun 12, 2007 12:15 PM PDT</abbr> to <abbr class="dtend" title="2007-06-12T13:15:00PDT">Jun 12, 2007 1:15 PM PDT</abbr></content>
<summary type="text">Recurring daily event: Jun 12, 2007 12:15 PM PDT to Jun 12, 2007 1:15 PM PDT</summary>
<link rel="self" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6" />
</entry>
Modifying an Item
An item may be updated by sending a
PUT request containing an Atom entry to the
edit URI found in the item's entry within the collection 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 an EIM-JSON or EIMML representation of the item. This representation defines a complete replacement for the existing item exposed by the
edit URI; there is no way to represent partial changes to an item. The Atom entry metadata is not stored.
The response to an update request includes an Atom entry document describing the updated item. 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. Since an item's URI is based on its UUID which cannot change after the item's creation, the response does not include
Location or
Content-Location headers.
The collection in which the item is being created is locked during the update process. All other clients attempting to perform write operations on the collection or its children during that time will receive a
423 Locked response.
Response Status Codes
- 200: The item was successfully modified
- 400: The request content could not be parsed, did not represent an Atom entry or contained an invalid representation
- 409: The item contained an iCalendar UID that is in use by an item already in the collection
- 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
- 423: The collection was locked and could not be updated
- 500: Unknown server error
Examples
This example shows a successful modify operation:
<<< REQUEST >>>
PUT /chandler/atom/item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6 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="application/eim+json">{"uuid":"8ed8bd32-18f1-11dc-e1d4-d2641e3508a6","records":{"item":{"ns":"http://osafoundation.org/eim/item/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"title":["text","Recurring daily event"],"triage":["text","200 -1181658614.11 1"],"hasBeenSent":["integer","0"],"needsReply":["integer","0"],"createdOn":["decimal","1181658614"]}},"modby":{"ns":"http://osafoundation.org/eim/modifiedBy/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"],"userid":["text","bcm"],"timestamp":["decimal","1181658622"],"action":["integer","500"]}},"note":{"ns":"http://osafoundation.org/eim/note/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"body":["clob",null],"icalUid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]}},"event":{"ns":"http://osafoundation.org/eim/event/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"dtstart":["text",";VALUE=DATE-TIME;TZID=America/Los_Angeles:20070612T121500"],"duration":["text","PT1H"],"location":["text","over there"],"rrule":["text","FREQ=DAILY;UNTIL=20070616T065900Z"],"exrule":["text",null],"rdate":["text",null],"exdate":["text",null],"status":["text","CONFIRMED"]}},"displayAlarm":{"ns":"http://osafoundation.org/eim/displayAlarm/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"description":["text",null],"trigger":["text",null],"duration":["text",null],"repeat":["integer",null]}}}}</content>
</entry>
<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "4skVIPCSm/Y8N3Z768oh63YmB1E="
Last-Modified: Fri, 13 Jul 2007 21:32:56 GMT
Content-Type: application/atom+xml
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns:app="http://www.w3.org/2007/app"
xmlns="http://www.w3.org/2005/Atom"
xml:base="http://example.org/chandler/atom/">
<id>urn:uuid:8ed8bd32-18f1-11dc-e1d4-d2641e3508a6</id>
<title type="text">Recurring daily event</title>
<updated>2007-07-13T21:32:56.222Z</updated>
<app:edited>2007-07-13T21:32:56.222Z</app:edited>
<published>2007-07-13T21:13:53.962Z</published>
<author>
<name>bcm</name>
</author>
<content type="html"><div class="vevent"><span class="summary">Recurring daily event</span>: <abbr class="dtstart" title="2007-06-12T12:15:00PDT">Jun 12, 2007 12:15 PM PDT</abbr> to <abbr class="dtend" title="2007-06-12T13:15:00PDT">Jun 12, 2007 1:15 PM PDT</abbr> at <span class="location">over there</span></div></content>
<summary type="text">Recurring daily event: Jun 12, 2007 12:15 PM PDT to Jun 12, 2007 1:15 PM PDT at over there</summary>
<link rel="self" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6/full/eim-json" />
<link rel="parent" type="application/atom+xml" href="collection/5658ce1e-491b-44ba-a65f-875571cfa939/full/eim-json" />
<link rel="expanded" type="application/atom+xml" href="expanded/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6/full/eim-json" />
<link rel="edit" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6" />
</entry>
This example shows a modify operation containing a record that specifies an iCalendar uid that is already in use by an existing item in the collection.
<<< REQUEST >>>
PUT /chandler/atom/item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6 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="application/eim+json">{"uuid":"8ed8bd32-18f1-11dc-e1d4-d2641e3508a6","records":{"item":{"ns":"http://osafoundation.org/eim/item/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"title":["text","Recurring daily event"],"triage":["text","200 -1181658614.11 1"],"hasBeenSent":["integer","0"],"needsReply":["integer","0"],"createdOn":["decimal","1181658614"]}},"modby":{"ns":"http://osafoundation.org/eim/modifiedBy/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"],"userid":["text","bcm"],"timestamp":["decimal","1181658622"],"action":["integer","500"]}},"note":{"ns":"http://osafoundation.org/eim/note/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"body":["clob",null],"icalUid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]}},"event":{"ns":"http://osafoundation.org/eim/event/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"dtstart":["text",";VALUE=DATE-TIME;TZID=America/Los_Angeles:20070612T121500"],"duration":["text","PT1H"],"location":["text","over there"],"rrule":["text","FREQ=DAILY;UNTIL=20070616T065900Z"],"exrule":["text",null],"rdate":["text",null],"exdate":["text",null],"status":["text","CONFIRMED"]}},"displayAlarm":{"ns":"http://osafoundation.org/eim/displayAlarm/0","key":{"uuid":["text","7ed8bd32-18f1-11dc-e1d4-d2641e3508a6"]},"fields":{"description":["text",null],"trigger":["text",null],"duration":["text",null],"repeat":["integer",null]}}}}</content>
</entry>
<<< RESPONSE >>>
HTTP/1.1 409 Conflict
Content-Type: application/xml
Content-Length: xxx
<?xml version='1.0' encoding='UTF-8'?>
<error xmlns="http://incubator.apache.org/abdera">
<code>409</code>
<message>iCal uid 7ed8bd32-18f1-11dc-e1d4-d2641e3508a6 already in use for collection 912b115d-d746-47c7-bb3a-b0aed623d0e6</message>
<no-uid-conflict xmlns="http://osafoundation.org/cosmo/Atom">
<existing-uuid>1f9f7ced-544e-419e-ba26-f3afdffa3000</existing-uuid>
<conflicting-uuid>8ed8bd32-18f1-11dc-e1d4-d2641e3508a6</conflicting-uuid>
</no-uid-conflict>
</error>
Deleting an Item
An item may be deleted by sending a
DELETE request to the
edit URI found in the item's entry within the collection feed. This functions as a
hard delete, removing the item from every collection in which it is a member.
The
uuid query parameter may be provided, identifying the UUID of a specific collection of which the item addressed by the URI is a member. This functions as a
soft delete, removing the item only from the specified collection.
The response does not include an entity.
The collection in which the item is being created is locked during the delete process. All other clients attempting to perform write operations on the collection or its children during that time will receive a
423 Locked response.
Response Status Codes
- 204: Success
- 409: The item for the provided UUID was not found or is not a collection
- 423: The collection was locked and could not be updated
- 500: Unknown server error
Examples
<<< REQUEST >>>
DELETE /chandler/atom/user/item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
<<< RESPONSE >>>
HTTP/1.1 204 No Content
Expanding a Recurring Item
An
expanded item feed may be returned by sending a
GET request to the the
expanded URI found in the item's entry within the collection feed. The URI may include projection and format identifiers and query parameters (see
CosmoFeedCollectionsAndItems for more information). The template for an item URI is
/atom/expanded/{uuid}[/{projection}[/{format}]][?{query string}].
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.
If the request URI included time-range query parameters, the feed includes an entry for the master item and an entry for each of the master's modifications and regular occurrences that begin or end within the specified time-range (except when the basic projection is used, in which case the master is excluded from the feed). If the request URI does not include any time-range query parameters, the feed includes only an entry for the master item.
The content of an item 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.
The feed and entry metadata elements are populated as per a collection feed.
Response Status Codes
- 200: Success
- 400: Invalid query parameters, or unsupported projection or data format
- 500: Unknown server error
Examples
<<< REQUEST >>>
GET /chandler/atom/expanded/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6?start=2007-06-12T00:00:00PST&end=2007-06-12T23:59:59PST HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
<<< RESPONSE >>>
HTTP/1.1 200 OK
ETag: "+lnma82AUCo2e6DZfzPaAtbXWqA="
Last-Modified: Fri, 13 Jul 2007 22:35:24 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:8ed8bd32-18f1-11dc-e1d4-d2641e3508a6</id>
<title type="text">Recurring daily event</title>
<updated>2007-07-13T22:35:24.747Z</updated>
<generator uri="http://cosmo.osafoundation.org/" version="0.7.0-SNAPSHOT-r5065">Chandler Server</generator>
<author>
<name>bcm</name>
<uri>user/bcm</uri>
</author>
<link rel="self" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6/full/eim-json" />
<entry xmlns:app="http://www.w3.org/2007/app">
<id>urn:uuid:8ed8bd32-18f1-11dc-e1d4-d2641e3508a6%3A20070614T191500Z</id>
<title type="text">Recurring daily event</title>
<updated>2007-07-13T22:35:24.747Z</updated>
<app:edited>2007-07-13T22:35:24.747Z</app:edited>
<published>2007-07-13T22:35:24.747Z</published>
<content type="html"><div class="vevent"><span class="summary">Recurring daily event</span>: <abbr class="dtstart" title="2007-06-14T12:15:00PDT">Jun 14, 2007 12:15 PM PDT</abbr> to <abbr class="dtend" title="2007-06-14T13:15:00PDT">Jun 14, 2007 1:15 PM PDT</abbr> at <span class="location">over there</span></div></content>
<summary type="text">Recurring daily event: Jun 14, 2007 12:15 PM PDT to Jun 14, 2007 1:15 PM PDT at over there</summary>
<link rel="self" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6:20070614T191500Z" />
</entry>
<entry xmlns:app="http://www.w3.org/2007/app">
<id>urn:uuid:8ed8bd32-18f1-11dc-e1d4-d2641e3508a6%3A20070613T191500Z</id>
<title type="text">Recurring daily event</title>
<updated>2007-07-13T22:35:24.747Z</updated>
<app:edited>2007-07-13T22:35:24.747Z</app:edited>
<published>2007-07-13T22:35:24.747Z</published>
<content type="html"><div class="vevent"><span class="summary">Recurring daily event</span>: <abbr class="dtstart" title="2007-06-13T12:15:00PDT">Jun 13, 2007 12:15 PM PDT</abbr> to <abbr class="dtend" title="2007-06-13T13:15:00PDT">Jun 13, 2007 1:15 PM PDT</abbr> at <span class="location">over there</span></div></content>
<summary type="text">Recurring daily event: Jun 13, 2007 12:15 PM PDT to Jun 13, 2007 1:15 PM PDT at over there</summary>
<link rel="self" type="application/atom+xml" href="item/8ed8bd32-18f1-11dc-e1d4-d2641e3508a6:20070613T191500Z" />
</entry>
</feed>
Adding an Item to a Collection
An item may be added to a collection other than one of which it is already a member by sending a
POST request to the URI of the collection in which the item is to be added. The content type of the request must be
application/x-www-form-urlencoded, and the content length must be greater than 0. The content of the request must be
URL-encoded form data. The form data must include a pair with name
uuid and the uuid of the item to add as the value.
The response does not included an entity.
The collection in which the item is being created is locked during the addition process. All other clients attempting to perform write operations on the collection or its children during that time will receive a
423 Locked response.
Response Status Codes
- 204: The item was successfully added to the collection
- 400: The request content did not contain a data pair with name
uuid and non-empty value, or an item with that uuid could not be found, or the item with that uuid is not a note
- 411: The request
Content-Length header was not provided or was not greater than 0
- 423: The collection was locked and could not be updated
- 500: Unknown server error
Examples
<<< REQUEST >>>
POST /chandler/atom/collection/5658ce1e-491b-44ba-a65f-875571cfa939 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
uuid=8ed8bd32-18f1-11dc-e1d4-d2641e3508a6
<<< RESPONSE >>>
HTTP/1.1 204 No Content