API : CardDAV : WebDAV methods

The CardDAV server answers the WebDAV methods below on https://api.telecomx.dk/carddav/…. Express has no native routing for PROPFIND and REPORT, so the whole tree is handled by one catch-all route that dispatches on the method. Anything not listed here is answered with 405 Method Not Allowed.

The body of PROPFIND, REPORT, PUT and POST is read as raw text (XML or vCard) with a limit of 10 MB - a larger body is cut off with 413 and the connection is closed. The limit has to be that high because a multiget of a whole address book, or a vCard with an embedded photo, is large.

Advertises the DAV capabilities of the server.

DAV: 1, 2, 3, addressbook
Allow: OPTIONS, GET, PUT, DELETE, PROPFIND, REPORT, POST

Note: the API servers global OPTIONS handler (CORS preflight and load balancer health checks) answers before the CardDAV router is reached, so in practice an OPTIONS request returns {“options”: true} with the CORS headers and not the two headers above. Clients discover the server with PROPFIND instead, which is what iOS and DAVx5 do, so this has no practical effect today.

Discovers collections and reads properties. Depth: 0 returns the resource itself, Depth: 1 also its children. The response is always 207 Multi-Status XML.

Any other path, including one with another employees id, answers 404.

PROPFIND /carddav/addressbooks/1234567890ABCDEF12345678/personal/ HTTP/1.1
Depth: 1
Content-Type: application/xml; charset=utf-8
 
<D:propfind xmlns:D="DAV:">
  <D:prop>
    <D:getetag/>
    <D:getcontenttype/>
  </D:prop>
</D:propfind>

Runs a CardDAV query against an address book collection. Two report types are supported:

sync-collection is not implemented. Any other report type answers 400 Unsupported REPORT type.

The response is 207 Multi-Status with getetag, getcontenttype and, when address-data was requested, the full vCard for each contact.

Returns a single contact.

The contact has to be in the book it is requested from: a personal contact fetched through /shared/ - or the other way round - answers 404. A contact belonging to another customer answers 403 access_denied.

Creates or updates a contact in the personal book. /shared/ and /colleagues/ are read-only and answer 403.

An embedded or referenced PHOTO is uploaded to the image server; if the upload fails the rest of the contact is still saved.

Deletes a contact from the personal book. /shared/ and /colleagues/ answer 403.

The contact is soft-deleted in the phonebook, exactly as a delete through the REST API.

Subscribes or unsubscribes an Apple device to push notifications for a collection - see Push notifications. POST /carddav/notify is a different thing entirely, see Notify.