CalDAV Developer's Guide

Google Calendar now provides a CalDAV interface for use by developers of calendar client applications. We have not provided a full implementation of all of the relevant specifications, however for many clients such as Apple iCal(TM) we should interoperate correctly.

Specifications

The specifications for this protocol are:

• HTTP Extensions for Distributed Authoring (WebDAV)
  • We support the HTTP methods GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND and PROPPATCH.
  • We do not support the HTTP methods LOCK, UNLOCK, COPY, MOVE, or MKCOL, or the If header.
  • We do not support arbitrary (user-defined) webdav properties.
  • We do not support WebDAV Access Control (rfc3744).
• Calendaring extension to WebDAV (CalDAV)
  • We support the HTTP method REPORT, but not all defined reports are implemented.
  • We provide a principal collection and a calendar collection for each calendar.
  • We do not support the HTTP method MKCALENDAR.
• HTTP Authentication: Basic and Digest Access Authentication

  We authenticate CalDAV clients using Basic HTTP Authentication. For security of your Google user name and password, we require CalDAV connections to use HTTPS. The client should authenticate using your full Google account email address (including the domain, "@gmail.com" or otherwise) and password.

• rfc2445bis: Internet Calendaring and Scheduling Core Object Specification (iCalendar)

  Data exposed in the CalDAV interface are formatted according to the iCalendar specification. We do not support arbitrary calendar and event properties or parameters; only those properties that directly correspond to Google Calendar's data model are retained. We currently do not support VTODO or VJOURNAL data.

• draft-desruisseaux-caldav-sched-03: Scheduling Extensions to CalDAV

  These extensions to CalDAV have been defined by Apple to support features of Apple iCal. We support a trivial "inbox", which is always empty. Invitations you receive are automatically delivered into your "events" collection rather than being placed into your "inbox". We use the "outbox" to enable a client to notify the server when it has completed modifying an event, so that participants are notified of the invitation. Similarly, the outbox is used by the client to respond to an event invitation. We do not support free-busy lookup.

• caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

  The "calendar ctag" is like a resource "etag"; it changes when anything in the calendar has changed. This allows the client to quickly determine that it does not need to synchronize any changed events.

Creating a connection with the CalDAV server

To use the CalDAV interface, a client program initially connects with the calendar server at one of two starting points. In either case, the connection must be made over HTTPS, and Basic authentication should be provided for the user's Google account, consisting of the full email address and password. The CalDAV server will refuse to authenticate a request unless it arrives over HTTPS with Basic authentication of a Google account. Attempting to connect over HTTP or with an an email/password that doesn't match a Google account results in an HTTP 401 (Unauthorized) response.

If the client program (such as Apple iCal) requires a principal collection as the starting point, the URI to connect to is

  https://www.google.com/calendar/dav/calid/user

Where calid should be replaced by the "calendar id" of the calendar to be accessed. This can be found through the Google Calendar web interface as follows: in the pull-down menu next to the calendar name, select "calendar settings". On the resulting page the calendar ID is shown in a section labelled "Calendar Address". The calendar id for a user's primary calendar is the same as that user's email address.

If a client program (such as Mozilla Sunbird) requires a calendar collection as the starting point, the URI to connect to is

  https://www.google.com/calendar/dav/calid/events

Where calid should be replaced by the "calendar id" of the calendar to be accessed, as above.