For developers and product teams building calendar-centric applications, integrating with Apple Calendar presents a unique challenge. Enter CalDAV, a versatile protocol that unlocks a world of possibilities for Apple Calendar integration and beyond.
CalDAV, WebDAV, and iCalendar
-
CalDAV and WebDAV: CalDAV, or Calendar Distributed Authoring and Versioning, is an extension of WebDAV, a protocol for collaborative editing and management of files on web servers. CalDAV extends WebDAV to support calendar-specific operations, providing a standardized way for clients to access and manage calendar events.
One unusual detail of WebDav is that this XML based protocol uses the HTTP methods PROPFIND and REPORT alot.
REPORT /bernard/work/ HTTP/1.1
Host: cal.example.com
Depth: 1
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-query xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:prop>
<D:getetag/>
<C:calendar-data>
<C:comp name="VCALENDAR">
<C:prop name="VERSION"/>
<C:comp name="VEVENT">
<C:prop name="SUMMARY"/>
<C:prop name="UID"/>
<C:prop name="DTSTART"/>
<C:prop name="DTEND"/>
<C:prop name="DURATION"/>
<C:prop name="RRULE"/>
<C:prop name="RDATE"/>
<C:prop name="EXRULE"/>
<C:prop name="EXDATE"/>
<C:prop name="RECURRENCE-ID"/>
</C:comp>
<C:comp name="VTIMEZONE"/>
</C:comp>
</C:calendar-data>
</D:prop>
<C:filter>
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VEVENT">
<C:time-range start="20060104T000000Z"
end="20060105T000000Z"/>
</C:comp-filter>
</C:comp-filter>
</C:filter>
</C:calendar-query>
-
iCalendar: iCalendar, or ICS, is a standard format for representing and exchanging calendaring and scheduling information. It is often used with CalDAV to facilitate the sharing of calendar events across different platforms and applications.
In the example below you see iCalendar payload inside of the ‘calendar-data’ XML tag:
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:response>
<D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-abcd2"</D:getetag>
<C:calendar-data>BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VTIMEZONE
LAST-MODIFIED:20040110T032845Z
TZID:US/Eastern
BEGIN:DAYLIGHT
DTSTART:20000404T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
TZNAME:EDT
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:20001026T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZNAME:EST
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
DTSTART;TZID=US/Eastern:20060102T120000
DURATION:PT1H
RRULE:FREQ=DAILY;COUNT=5
SUMMARY:Event #2
UID:00959BC664CA650E933C892C@example.com
END:VEVENT
BEGIN:VEVENT
DTSTART;TZID=US/Eastern:20060104T140000
DURATION:PT1H
RECURRENCE-ID;TZID=US/Eastern:20060104T120000
SUMMARY:Event #2 bis
UID:00959BC664CA650E933C892C@example.com
END:VEVENT
BEGIN:VEVENT
DTSTART;TZID=US/Eastern:20060106T140000
DURATION:PT1H
RECURRENCE-ID;TZID=US/Eastern:20060106T120000
SUMMARY:Event #2 bis bis
UID:00959BC664CA650E933C892C@example.com
END:VEVENT
END:VCALENDAR
</C:calendar-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
...
Diverse Calendar Providers
Major players in the calendar space, such as Apple, Yahoo, Google, and Microsoft, support CalDAV. However, each provider has its own nuances and capabilities. For example, the CalDav protocol defines calendar components (like event, a to-do, a journal entry, time zone information, or free/busy time information, or an alarm) but not all servers will support all those components (most will support event, time zone info and to-do though).
-
Apple Calendar: Apple’s iCloud supports CalDAV, allowing seamless synchronization across Apple devices. Integrating Apple Calendars involves obtaining the CalDAV URL and using the CalDAV protocol for communication.
-
Google Calendar: Google provides both CalDAV and proprietary APIs. While CalDAV is widely supported, Google’s API might offer additional features and flexibility for integration.
-
Microsoft Exchange: Microsoft Exchange supports both CalDAV and proprietary APIs (like ActiveSync and EWS). Developers can choose the protocol based on their specific requirements.
Integrating Apple Calendars using CalDAV
To integrate Apple Calendars, developers need to authenticate with iCloud (using app-password), obtain the CalDAV URL, and use CalDAV requests for operations like event creation, deletion, or retrieval. Let’s walk through some of the key methods that will help you start integrating with Apple/iCloud.
Get user/principle information
PROPFIND / HTTP/1.1
Host: caldav.icloud.com
Content-Type: application/xml; charset=utf-8
Authorization: Basic basicValue
<d:propfind xmlns:d="DAV:">
<d:prop>
<d:current-user-principal/>
</d:prop>
</d:propfind>
Response - properties are successfully retrieved when you see status HTTP/1.1 200 OK
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/</href>
<propstat>
<prop>
<current-user-principal xmlns="DAV:">
<href xmlns="DAV:">/200385701/principal/</href>
</current-user-principal>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Discover the principal’s CalDav server
PROPFIND /200385701/principal/ HTTP/1.1
Host: caldav.icloud.com
Content-Type: application/xml; charset=utf-8
Authorization: Basic basicValue
<d:propfind xmlns:d="DAV:" xmlns:cal="urn:ietf:params:xml:ns:caldav" xmlns:cs="http://calendarserver.org/ns/">
<d:prop>
<cal:calendar-home-set/>
<d:group-membership/>
</d:prop>
</d:propfind>
Response - group-membership is not defined for this user (HTTP/1.1 404 Not Found) but calendar-home-set tells you the CalDav server (https://p34-caldav.icloud.com).
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/principal/</href>
<propstat>
<prop>
<calendar-home-set xmlns="urn:ietf:params:xml:ns:caldav">
<href xmlns="DAV:">https://p34-caldav.icloud.com:443/200385701/calendars/</href>
</calendar-home-set>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
<propstat>
<prop>
<group-membership xmlns="DAV:"/>
</prop>
<status>HTTP/1.1 404 Not Found</status>
</propstat>
</response>
</multistatus>
Communicate with the principal’s CalDav instance (https://p34-caldav.icloud.com) from now on!
Get a list of calendars
Some properties, like calendar-color, are clearly provider specific.
PROPFIND /200385701/calendars/ HTTP/1.1
Host: p34-caldav.icloud.com
Content-Type: application/xml; charset=utf-8
Authorization: Basic basicValue
<d:propfind xmlns:d="DAV:" xmlns:apple="http://apple.com/ns/ical/" xmlns:cs="http://calendarserver.org/ns/" xmlns:cal="urn:ietf:params:xml:ns:caldav">
<d:prop>
<d:current-user-privilege-set/>
<d:resourcetype />
<d:displayname />
<apple:calendar-color/>
<cs:source/>
<cal:supported-calendar-component-set/>
</d:prop>
</d:propfind>
Response - calendar-component-set shows you what a calendar supports: events, to-dos, free/busy information.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/calendars/</href>
<propstat>
<prop>
<current-user-privilege-set xmlns="DAV:">
<privilege>
<read/>
</privilege>
...
</current-user-privilege-set>
<resourcetype xmlns="DAV:">
<collection/>
</resourcetype>
<displayname xmlns="DAV:">User name</displayname>
<supported-calendar-component-set xmlns="urn:ietf:params:xml:ns:caldav">
<comp name='VEVENT' xmlns='urn:ietf:params:xml:ns:caldav'/>
<comp name='VTODO' xmlns='urn:ietf:params:xml:ns:caldav'/>
<comp name='VFREEBUSY' xmlns='urn:ietf:params:xml:ns:caldav'/>
</supported-calendar-component-set>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
<propstat>
<prop>
<calendar-color xmlns="http://apple.com/ns/ical/"/>
<source xmlns="http://calendarserver.org/ns/"/>
</prop>
<status>HTTP/1.1 404 Not Found</status>
</propstat>
</response>
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/</href>
<propstat>
<prop>
<current-user-privilege-set xmlns="DAV:">
<privilege>
<read/>
</privilege>
...
</current-user-privilege-set>
<resourcetype xmlns="DAV:">
<collection/>
<calendar xmlns="urn:ietf:params:xml:ns:caldav"/>
</resourcetype>
<displayname xmlns="DAV:">New calendars</displayname>
<calendar-color xmlns="http://apple.com/ns/ical/">#FF2D55FF</calendar-color>
<supported-calendar-component-set xmlns="urn:ietf:params:xml:ns:caldav">
<comp name='VEVENT' xmlns='urn:ietf:params:xml:ns:caldav'/>
</supported-calendar-component-set>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
<propstat>
<prop>
<source xmlns="http://calendarserver.org/ns/"/>
</prop>
<status>HTTP/1.1 404 Not Found</status>
</propstat>
</response>
...
</multistatus>
Request a list of calendar events
REPORT /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/
Host: p34-caldav.icloud.com
Content-Type: text/plain; charset=utf-8
Authorization: Basic basicValue
Depth: 1
<c:calendar-query xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:d="DAV:">
<d:prop>
<d:getetag/>
</d:prop>
<c:filter>
<c:comp-filter name="VCALENDAR">
<c:comp-filter name="VEVENT">
</c:comp-filter>
</c:comp-filter>
</c:filter>
</c:calendar-query>
Response - see href links. Some servers can return event details when calendar-data is requested (see examples below). Keep track of etags, they change when the records change.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response>
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/</href>
<propstat>
<prop>
<getetag xmlns="DAV:">"kiix2mif"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/1.ics</href>
<propstat>
<prop>
<getetag xmlns="DAV:">"lrgcxs0m"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/2.ics</href>
<propstat>
<prop>
<getetag xmlns="DAV:">"lrgcxs0m"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
...
</multistatus>
Retrieve details of multiple events:
Simply specify the href links and request calendar-data.
REPORT /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/
Host: p34-caldav.icloud.com
Authorization: Basic basicValue
Depth: 1
Content-Type: text/plain; charset=utf-8
<c:calendar-multiget xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:d="DAV:">
<d:prop>
<d:getetag/>
<c:calendar-data></c:calendar-data>
</d:prop>
<d:href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/1.ics</d:href>
<d:href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/2.ics</d:href>
</c:calendar-multiget>
Response - always check response status (there is one per event) as some events may be gone (HTTP/1.1 404 Not Found). calendar-data is the event data in iCalendar format.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/2.ics</href>
<status>HTTP/1.1 404 Not Found</status>
</response>
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/1.ics</href>
<propstat>
<prop>
<getetag xmlns="DAV:">"lqghznnp"</getetag>
<calendar-data xmlns="urn:ietf:params:xml:ns:caldav"><![CDATA[BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Apple Inc.//macOS 14.2.1//EN
VERSION:2.0
BEGIN:VEVENT
CREATED:20231222T103741Z
DTEND;TZID=Africa/Bamako:20240114T100000
DTSTAMP:20240109T073000Z
DTSTART;TZID=Africa/Bamako:20240114T090000
LAST-MODIFIED:20240109T070811Z
LOCATION:New York County\, NY\nUnited States
SEQUENCE:1
SUMMARY:Single event
UID:1
X-APPLE-CREATOR-IDENTITY:com.apple.calendar
X-APPLE-CREATOR-TEAM-IDENTITY:0000000000
...
END:VEVENT
BEGIN:VTIMEZONE
TZID:Africa/Bamako
X-LIC-LOCATION:Africa/Bamako
BEGIN:STANDARD
DTSTART:19120101T000000
RDATE:19120101T000000
TZNAME:GMT
TZOFFSETFROM:-001608
TZOFFSETTO:+0000
END:STANDARD
END:VTIMEZONE
END:VCALENDAR
]]></calendar-data>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Report events in a time range
Here is an alternative way to get event details (calendar-data) for multiple events.
REPORT /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/
Host: p34-caldav.icloud.com
Authorization: Basic basicValue
Depth: 1
Content-Type: text/plain; charset=utf-8
<c:calendar-query xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:d="DAV:">
<d:prop>
<d:getetag/>
<c:calendar-data>
<c:comp name="VCALENDAR">
<c:prop name="VERSION"/>
<c:comp name="VEVENT">
<c:prop name="UID"/>
<c:prop name="CREATED"/>
<c:prop name="LAST-MODIFIED"/>
<c:prop name="SUMMARY"/>
<c:prop name="DTSTART"/>
<c:prop name="DTEND"/>
<c:prop name="ORGANIZER"/>
<c:prop name="STATUS"/>
<c:prop name="RECURRENCE-ID"/>
<c:prop name="RRULE"/>
<c:prop name="LOCATION"/>
<c:prop name="TRANSP"/>
<c:prop name="CATEGORIES"/>
<c:prop name="ATTACH"/>
<c:prop name="ATTENDEE"/>
</c:comp>
<c:comp name="VTIMEZONE"/>
</c:comp>
</c:calendar-data>
</d:prop>
<c:filter>
<c:comp-filter name="VCALENDAR">
<c:comp-filter name="VEVENT">
<c:time-range start="20240125T000000Z" end="20240126T000000Z"/>
</c:comp-filter>
</c:comp-filter>
</c:filter>
</c:calendar-query>
Response - extract event id from the href links and keep track of etags.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response>
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/603275E4-6A47-4EFA-BAEF-CCD33A314C30.ics</href>
<propstat>
<prop>
<getetag xmlns="DAV:">"lreo54jn"</getetag>
<calendar-data xmlns="urn:ietf:params:xml:ns:caldav"><![CDATA[BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
CREATED:20240115T083404Z
DTEND;VALUE=DATE:20240126
DTSTART;VALUE=DATE:20240125
LAST-MODIFIED:20240115T083404Z
RRULE:FREQ=DAILY;COUNT=3
SUMMARY:Bamako All
UID:603275E4-6A47-4EFA-BAEF-CCD33A314C30
TRANSP:TRANSPARENT
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder
TRIGGER:-PT15H
UID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
X-APPLE-DEFAULT-ALARM:TRUE
X-WR-ALARMUID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
END:VALARM
END:VEVENT
END:VCALENDAR
]]></calendar-data>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Get an event by id
Append .ics after an event id (i.e. 603275E4-6A47-4EFA-BAEF-CCD33A314C30). Essentially, you’re requesting an .ics file.
GET /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/603275E4-6A47-4EFA-BAEF-CCD33A314C30.ics HTTP/1.1
Authorization: Basic basicValue
Host: p34-caldav.icloud.com
Response - here, response is not XML but iCalendar.
HTTP/1.1 200 OK
Server: AppleHttpServer/78689afb4479
Content-Type: text/calendar; charset=UTF-8
ETag: "lreo54jn"
DAV: 1, access-control
BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Apple Inc.//macOS 14.2.1//EN
VERSION:2.0
BEGIN:VEVENT
CREATED:20240115T083404Z
DTEND;VALUE=DATE:20240126
DTSTAMP:20240115T083404Z
DTSTART;VALUE=DATE:20240125
LAST-MODIFIED:20240115T083404Z
RRULE:FREQ=DAILY;COUNT=3
SEQUENCE:0
SUMMARY:Bamako All
UID:603275E4-6A47-4EFA-BAEF-CCD33A314C30
X-APPLE-CREATOR-IDENTITY:com.apple.calendar
X-APPLE-CREATOR-TEAM-IDENTITY:0000000000
TRANSP:TRANSPARENT
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder
TRIGGER:-PT15H
UID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
X-APPLE-DEFAULT-ALARM:TRUE
X-WR-ALARMUID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
END:VALARM
END:VEVENT
END:VCALENDAR
Update an event
There is no patching! So, load an event, make changes and send its full payload back to the server. A new event is created using PUT too, simply generate a new UUID for your new event.
PUT /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/603275E4-6A47-4EFA-BAEF-CCD33A314C30.ics HTTP/1.1
Authorization: Basic basicValue
Host: p34-caldav.icloud.com
BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Apple Inc.//macOS 14.2.1//EN
VERSION:2.0
BEGIN:VEVENT
CREATED:20240115T083404Z
DTEND;VALUE=DATE:20240126
DTSTAMP:20240115T083404Z
DTSTART;VALUE=DATE:20240125
LAST-MODIFIED:20240115T083404Z
RRULE:FREQ=DAILY;COUNT=3
SEQUENCE:0
SUMMARY:Bamako All 2
UID:603275E4-6A47-4EFA-BAEF-CCD33A314C30
X-APPLE-CREATOR-IDENTITY:com.apple.calendar
X-APPLE-CREATOR-TEAM-IDENTITY:0000000000
TRANSP:TRANSPARENT
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder
TRIGGER:-PT15H
UID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
X-APPLE-DEFAULT-ALARM:TRUE
X-WR-ALARMUID:E40DEE70-5AF7-43D6-93FC-3D2C755A29F6
END:VALARM
END:VEVENT
END:VCALENDAR
Response - no content here, but capture the etag!
TTP/1.1 204 No Content
Server: AppleHttpServer/78689afb4479
X-Apple-API-Version: v1
Etag: "lrhk7ybi"
Syncing
Let’s assume that your CalDAV server supports the collection synchronization extension (most calendar providers do).
If the DAV:sync-collection report is implemented by a WebDAV server, then the server MUST list the report in the “DAV:supported-report-set” property on any collection that supports synchronization.
Initial Sync
No sync token is specified yet.
REPORT /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/
Authorization: Basic basicValue
Content-Type: text/xml; charset=utf-8
Depth: 1
Host: p34-caldav.icloud.com
<d:sync-collection xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
<d:sync-token/>
<d:sync-level>1</d:sync-level>
<d:limit>
<d:nresults>10</d:nresults>
</d:limit>
<d:prop>
<d:getcontenttype/>
<d:getetag/>
</d:prop>
</d:sync-collection>
Response - CalDAV server will start returning all events (10 records per page) and a sync token to receive the next page. 1st response record is about the calendar itself.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/</href>
<propstat>
<prop>
<getcontenttype xmlns="DAV:">httpd/unix-directory</getcontenttype>
<getetag xmlns="DAV:">"kiix2min"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/8A4BFE75-91F3-4FF6-AF3D-9221B0587C6C.ics</href>
<propstat>
<prop>
<getcontenttype xmlns="DAV:">text/calendar</getcontenttype>
<getetag xmlns="DAV:">"lralxxtk"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
...
<sync-token>HwoQEgwAAGbI6heuOgAAAAEYARgAIhYIlZjF9sL437yDARDR3sXqpc+jt4UBKAA=</sync-token>
</multistatus>
Incremental Sync (or next page of the initial sync)
Request the ‘sync-collection’ with a sync token now.
REPORT /20038570152/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/ HTTP/1.1
Authorization: Basic basicValue
Content-Type: text/xml; charset=utf-8
Depth: 1
Host: p34-caldav.icloud.com
<d:sync-collection xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
<d:sync-token>HwoQEgwAAGay9UzEEAAAAAEYARgAIhYIlZjF9sL437yDARDR3sXqpc+jt4UBKAA=</d:sync-token>
<d:sync-level>1</d:sync-level>
<d:limit>
<d:nresults>10</d:nresults>
</d:limit>
<d:prop>
<d:getcontenttype/>
<d:getetag/>
</d:prop>
</d:sync-collection>
Response - capture the new sync token and continue paging until you get 0 records. Deleted events show the status ‘HTTP/1.1 404 Not Found’.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/</href>
<propstat>
<prop>
<getcontenttype xmlns="DAV:">httpd/unix-directory</getcontenttype>
<getetag xmlns="DAV:">"kiix2min"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/8A4BFE75-91F3-4FF6-AF3D-9221B0587C6C.ics</href>
<propstat>
<prop>
<getcontenttype xmlns="DAV:">text/calendar</getcontenttype>
<getetag xmlns="DAV:">"lralxxtk"</getetag>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/47474204-131F-4E09-B866-204C892781DE.ics</href>
<status>HTTP/1.1 404 Not Found</status>
</response>
<sync-token>HwoQEgwAAGbI6heuOgAAAAEYARgAIhYIlZjF9sL437yDARDR3sXqpc+jt4UBKAA=</sync-token>
</multistatus>
Sync token property
You can get the latest sync token without doing the full initial sync.
PROPFIND /200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/
Authorization: Basic basicValue
Depth: 0
Content-Type: text/plain; charset=utf-8
Host: p34-caldav.icloud.com
<d:propfind xmlns:d="DAV:" xmlns:cs="http://calendarserver.org/ns/">
<d:prop>
<d:displayname />
<cs:getctag />
<d:sync-token />
</d:prop>
</d:propfind>
Response - capture the sync token and use it for receiving updates in the future.
HTTP/1.1 207 Multi-Status
Server: AppleHttpServer/78689afb4479
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<multistatus xmlns="DAV:">
<response xmlns="DAV:">
<href>/200385701/calendars/2b0158b9-9c73-49e8-92a9-9aefbbec3534/</href>
<propstat>
<prop>
<displayname xmlns="DAV:">home</displayname>
<getctag xmlns="http://calendarserver.org/ns/">HwoQEgwAAGay9UzEEAAAAAEYARgAIhYIlZjF9sL437yDARDR3sXqpc+jt4UBKAA=</getctag>
<sync-token xmlns="DAV:">HwoQEgwAAGay9UzEEAAAAAEYARgAIhYIlZjF9sL437yDARDR3sXqpc+jt4UBKAA=</sync-token>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Harnessing the Power of Aurinko
CalDAV, while powerful, comes with complexities. Some challenges include dealing with different implementations across providers, handling recurring events, and managing time zones consistently. Developers should be prepared to address these intricacies during implementation.
Aurinko’s API gateway abstracts the intricacies of CalDAV, handling protocol-specific features behind the scenes (Appple/iCloud at the moment). This allows developers to focus on building features without getting bogged down by the complexities of CalDAV’s XML-based requests and responses.
By leveraging the Aurinko Calendar API, developers can enhance their applications with robust calendaring features while enjoying the benefits of a RESTful architecture.