CalAtom

Rob Yates and Dan Gurney

Using the Atom Publishing Protocol for Calendaring

Agenda

• Atom Introduction
• What google did
• CRUD operations in CalAtom
• Query operations in CalAtom
• Summary

Atom Introduction - Syndication

• Atom Syndication Format - "RSS without the bugs"
• Became RFC4287 in August 2005
• Designed to carry arbitrary payload e.g. iCalendar
• either inline

   <feed xmlns="http://www.w3.org/2005/Atom">
     <title type="text">dan's calendar</title>
     <updated>2005-07-31T12:29:29Z</updated>
     <id>tag:example.org,2003:3</id>
     <link rel="self" type="application/atom+xml"
      href="http://example.org/feed.atom"/>
     <entry>
       <title>CalAtom Presentation</title>
       <id>tag:example.org,2003:3.2397</id>
       <updated>2005-07-31T12:29:29Z</updated>
       <author><name>Dan Gurney</name></author>
       <content type="text/calendar" xml:lang="en">
        BEGIN:VCALENDAR
		VERSION:2.0
		PRODID:-//hacksw/handcal//NONSGML v1.0//EN
		BEGIN:VEVENT
		DTSTART:19970714T170000Z
		DTEND:19970715T035959Z
		SUMMARY:CalAtom Presentaion
		END:VEVENT
        END:VCALENDAR
       </content>
     </entry>
   </feed>

Atom Introduction - Syndication

• Atom Syndication Format - "RSS without the bugs"
• Became RFC4287 in August 2005
• Designed to carry arbitrary payload e.g. iCalendar
• or via a link

   <feed xmlns="http://www.w3.org/2005/Atom">
     <title type="text">dan's calendar</title>
     <updated>2005-07-31T12:29:29Z</updated>
     <id>tag:example.org,2003:3</id>
     <link rel="self" type="application/atom+xml"
      href="http://example.org/feed.atom"/>
     <entry>
       <title>CalAtom Presentation</title>
       <id>tag:example.org,2003:3.2397</id>
       <updated>2005-07-31T12:29:29Z</updated>
       <author><name>Dan Gurney</name></author>
       <content type="text/calendar" src="http://example.org/calendar/1.ics"/>
     </entry>
   </feed>

Atom Introduction - Syndication

• Atom Syndication Format - "RSS without the bugs"
• Became RFC4287 in August 2005
• Designed to carry arbitrary payload e.g. iCalendar
• can even have alternate represenations

   <feed xmlns="http://www.w3.org/2005/Atom">
     <title type="text">dan's calendar</title>
     <updated>2005-07-31T12:29:29Z</updated>
     <id>tag:example.org,2003:3</id>
     <link rel="self" type="application/atom+xml"
      href="http://example.org/feed.atom"/>
     <entry>
       <title>CalAtom Presentation</title>
       <id>tag:example.org,2003:3.2397</id>
       <updated>2005-07-31T12:29:29Z</updated>
       <author><name>Dan Gurney</name></author>
       <link type="application/calendar+xml" href="http://example.org/calendar/1.xml"/>
       <content type="text/calendar" src="http://example.org/calendar/1.ics"/>
     </entry>
   </feed>

Atom Introduction - Publishing

• Atom Publishing Protocol - currently in draft
• Provides REST mechanism to Create, Read, Update and Delete resources
• Provides paged collection navigation
• Provides introspection document for discovery of capabilities
• Similar to WebDav, simpler, less functionality
• no additional HTTP verbs
• no move or copy
• collections provided as feeds

Atom Introduction - Publishing

• e.g. create a blog post

   POST /myblog/entries HTTP/1.1
   Host: example.org
   User-Agent: Thingio/1.0
   Content-Type: application/atom+xml
   Content-Length: nnn

   <entry xmlns="http://www.w3.org/2005/Atom">
     <title>Atom-Powered Robots Run Amok</title>
     <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a$lt;/id>
     <updated>2003-12-13T18:30:02Z</updated>
     <content>Some text.$lt;/content>
   </entry>

   response

   HTTP/1.1 201 Created
   Date: Fri, 7 Oct 2005 17:17:11 GMT
   Content-Length: 0
   Location: http://example.org/edit/first-post.atom
   Content-Location: http://example.org/edit/first-post.atom

   <entry xmlns="http://www.w3.org/2005/Atom">
     <title>Atom-Powered Robots Run Amok</title>
     <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a$lt;/id>
     <updated>2003-12-13T18:30:02Z</updated>
     <content>Some text.$lt;/content>
   </entry>

Atom Introduction - Publishing

• accepts media posts which create "media link entries"
• currently a proposal

POST /calendar HTTP/1.1
Content- Type: text/calendar
...

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR

with response

HTTP/1.1 201 Created
Location: http://example.org/calendar/1.atom

<entry xmlns="http://www.w3.org/2005/Atom">
 <title>Bastille Day Party</title>
 <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
 <updated>2003-12-13T18:30:02Z</updated>
 <author><name>John Doe</name></author>
 <summary type="text" />
 <content type="text/calendar" src="http://example.org/calendar/1.ics"/>
 <link rel="edit" type="application/atom+xml" href="http://example.org/calendar/1.atom" />
 <link rel="edit-media" type="text/calendar" href="http://example.org/calendar/1.ics" />
</entry>

Atom Introduction - Introspection

• Describes available collections
• The introspection document below contains a reference to the owner's blog, picture folder and calendar
• The accept element describes their allowed contents

<service xmlns="http://purl.org/atom/app#"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace title="Dan's Site" >
    <collection
      title="My Blog Entries"
      href="http://example.org/main">
    </collection>
    <collection
      title="My Pictures"
      href="http://example.org/pic" >
      <accept>image/*</accept>
    </collection>
    <collection>
	  title="My Calendar"
	  href="http://example.org/calendar" >
	  <accept>text/calendar,application/calendar+xml</accept>
    </collection>
  </workspace>
</service>

What google did

• Utilized the Atom Publishing Protocol for CRUD operations
• Represented the collection of Calendar events as a feed
• Created a new Calendaring representation based on an Atom Entry by introducing proprietary atom extensions

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/g/2005#event'></category>
  <title type='text'>Tennis with Beth</title>
  <content type='text'>Meet for a quick lesson.</content>
  <author>
    <name>Jo March</name>
    <email>jo@gmail.com</email>
  </author>
  <gd:transparency
    value='http://schemas.google.com/g/2005#event.opaque'>
  </gd:transparency>
  <gd:eventStatus
    value='http://schemas.google.com/g/2005#event.confirmed'>
  </gd:eventStatus>
  <gd:where valueString='Rolling Lawn Courts'></gd:where>
  <gd:when startTime='2006-04-17T15:00:00.000Z'
    endTime='2006-04-17T17:00:00.000Z'></gd:when>
</entry>

CalAtom

• Utilizes the Atom Publishing Protocol for CRUD operations
• Represents the collection of Calendar events as a feed
• Reuses existing calendaring standards e.g. iCalendar, xCalendar

CalAtom - creating a calendar event

POST /calendar HTTP/1.1
Content- Type: text/calendar
...

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR

with response

HTTP/1.1 201 Created
Content- Type: application/atom+xml; charset="utf-8"
Content- Location: http://example.org/calendar/1.atom
Location: http://example.org/calendar/1.atom

<entry xmlns="http://www.w3.org/2005/Atom">
 <title>Bastille Day Party</title>
 <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
 <updated>2003-12-13T18:30:02Z</updated>
 <author><name>John Doe</name></author>
 <summary type="text" />
 <content type="text/calendar" src=http://example.org/calendar/1.ics/>
 <link rel="edit" type="application/atom+xml" href="http://example.org/calendar/1.atom" />
 <link rel="edit-media" type="text/calendar" href="http://example.org/calendar/1.ics" />
 <link rel="alternate" type="application/calendar+xml" href="http://example.org/calendar/1.xml" /> <-- xCalendar represenation
 <link rel="edit-media" type="application/calendar+xml" href="http://example.org/calendar/1.xml" /> <-- xCalendar representation 
</entry>

CalAtom - updating a calendar event

PUT /calendar/1.ics HTTP/1.1
Content- Type: text/calendar
...

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party with an update
END:VEVENT
END:VCALENDAR

with response

HTTP/1.1 200 OK

CalAtom - listing the events

GET /calendar HTTP/1.1
...

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>My Calendar</title>
  <link href="http://example.org/calendar"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
  <entry xmlns="http://www.w3.org/2005/Atom">
   <title>Bastille Day Party</title>
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <author><name>John Doe</name></author>
   <summary type="text" />
   <content type="text/calendar" src=http://example.org/calendar/1.ics/>
   <link rel="edit" type="application/atom+xml" href="http://example.org/calendar/1.atom" />
   <link rel="edit-media" type="text/calendar" href="http://example.org/calendar/1.ics" />
   <link rel="alternate" type="application/calendar+xml" href="http://example.org/calendar/1.xml" />
   <link rel="edit-media" type="application/calendar+xml" href="http://example.org/calendar/1.xml" />
  </entry>
  <entry xmlns="http://www.w3.org/2005/Atom">
   <title>Queens Birthday Party</title>
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efb6a</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <author><name>John Doe</name></author>
   <summary type="text" />
   <content type="text/calendar" src=http://example.org/calendar/2.ics/>
   <link rel="edit" type="application/atom+xml" href="http://example.org/calendar/2.atom" />
   <link rel="edit-media" type="text/calendar" href="http://example.org/calendar/2.ics" />
   <link rel="alternate" type="application/calendar+xml" href="http://example.org/calendar/2.xml" />
   <link rel="edit-media" type="application/calendar+xml" href="http://example.org/calendar/2.xml" />
  </entry>
 </feed>

CalAtom - Querying Requirements

• MUST make frequent queries simple e.g.
• Find the events for this week
• Find the freetime for this week
• SHOULD support optionally more complex queries
• Events that have the ATTENDEE property with the value "mailto:lisa@example.com" and for which the PARTSTAT parameter is set to "NEEDS-ACTION"
• SHOULD be extensible if additional data is mixed in with the default representation e.g. location as structured data
• find all the events in Massachusetts

CalAtom - Querying - An Approach

• Server provides 3 logical feeds for querying
• All contain an inline xCalendar payload
• Non-fanned out
• Fanned out
• Fanned out freebusy <- used for freetime lookups only, so event details not available
• "Fanned out" entries contain links to editable representations of repeat parents

CalAtom - ex of fanned out feed

GET /calendar/fanned HTTP/1.1
...

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>My Calendar</title>
  <link href="http://example.org/calendar"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
  <entry>
   <title>Bastille Day Party</title>
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <author><name>John Doe</name></author>
   <summary type="text" />
   <content type="application/calendar+xml">
    <vcalendar version="2.0" prodid="-//hacksw/handcal//NONSGML 1.0//EN"> <--- fanned out
     <vevent>
      <uid>19970901T130000Z-123401@host.com</uid>
      <dtstamp>19970901T130000Z</dtstamp>
      <dtstart>19970903T163000Z</dtstart>
      <dtend>19970903T190000Z</dtend>
      <summary>Bastille Day</summary>
      <class>PRIVATE</class>
     </vevent>
   </vcalendar>
   </content>
   <link rel="alternate" type="text/calendar" href="http://example.org/calendar/1.ics" />   <-- editable representations
   <link rel="edit-media" type="text/calendar" href="http://example.org/calendar/1.ics" />      repeat parent (if applicable)
   <link rel="alternate" type="application/calendar+xml" href="http://example.org/calendar/1.xml" />
   <link rel="edit-media" type="application/calendar+xml" href="http://example.org/calendar/1.xml" />
  </entry>
  <entry>
   <title>Queens Birthday Party</title>
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efb6a</id>
   ...
  </entry>
 </feed>

CalAtom - query

• For all three feeds support the following query parameters
• start-min - Earliest event start time to match
• start-max - Latest event start time to match
• q - full text query
• xpath - an xpath expression used to filter the returned entries

CalAtom - query examples

• All events with a start time between January 3rd, 2006 to January 5th, 2006
• ?start-min=20060103T000000Z&start-max=20060105T000000Z
• Return the VEVENT components that have the ATTENDEE property with the value "mailto:lisa@example.com" and for which the PARTSTAT parameter is set to "NEEDS-ACTION"
• ?xpath=/feed/entry[content/vcalendar/vevent /attendee[.="mailto:lisa@example.com" and @partstat="NEEDS-ACTION"]]

Why CalAtom?

• Lower barrier to entry, fewer features (80/20 rule?)
• Consistent with blogging approach, reuses introspection discovery mechanism, etc.
• Can benefit from future blogging atom extensions e.g. comments, reply-to