Cardhop 1 0 4 – Manage Your Contacts Address Book

Posted on  by

‎Until now, managing and interacting with your contacts has been a real frustration. Cardhop's magical parsing engine is incredibly intuitive, letting you search, add, edit, and interact with your contacts using a simple sentence! Just type in 'John G' and John's card will instantly appear. For example if Brian is saved to speed dial number 2 you would hold down 2. If your contacts speed dial number has more than one digit, hold down the last digit. For example, if 324 is the speed dial number you would tap 3 and 2 but hold down 4.

Cardhop 1 0 4 – manage your contacts address booking

Google Contacts now provides a CardDAV interface that you can use to view andmanage your contacts using the CardDAV protocol.

Contacts are stored in the user's Google Account; most Google services haveaccess to the contact list. Your client application can use the CardDAV API tocreate new contacts, edit or delete existing contacts, and query for contactsthat match particular criteria.

Specifications

We have not implemented the full specification, however many clients such asApple iOS™ Contacts and Apple Mac™ OSshould interoperate correctly.

For each relevant specification, Google's CardDAV support is as follows:

  • rfc2518: HTTP Extensions for Distributed Authoring(WebDAV)
    • Supports the HTTP methods GET, PUT, DELETE, OPTIONS, andPROPFIND.
    • Does not support the HTTP methods LOCK, UNLOCK, COPY, MOVE, orMKCOL.
    • Does not support arbitrary (user-defined) WebDAV properties.
    • Does not support WebDAV Access Control (rfc3744).
  • rfc5995: Using POST to Add Members to WebDAV Collections
    • Supports creating new contacts without specifying an ID.
  • rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring andVersioning (WebDAV)
    • Supports the HTTP method REPORT, but not all defined reports areimplemented.
    • Supports providing a principal collection and a contacts collection.
  • rfc6578: Collection Synchronization for WebDAV
    • Client applications must switch to this mode of operation after theinitial sync.
  • rfc6749: The OAuth 2.0 Authorization Framework andrfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
    • Supports authenticating CardDAV client programs using OAuth 2.0 HTTPAuthentication. Google does not support any other authentication method.For security of contact data, we require CardDAV connections to useHTTPS.
  • rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) andvCard Extensions to WebDAV (CardDAV)
    • Bootstrapping of CardDAV URLs must take place according to section 6 ofrfc6764.
  • Supports caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV,which is shared between the CardDAV and CalDAV specifications. The contactsctag is like a resource ETag; it changes when anything in the contactaddress book has changed. This allows the client program to quickly determine that itdoes not need to synchronize any changed contacts.
  • Google uses VCard 3.0 as the contact encoding format. See: rfc6350: VCard 3.0.

Google’s CardDAV requires OAuth 2.0

Google’s CardDAV interface requires OAuth 2.0. Refer to the linkeddocumentation below for information on using OAuth 2.0 to access Google APIs:

Connecting to Google's CardDAV server

The CardDAV protocol allows discovery of the address book and contact resourcesURIs. You must not hardcode any URI as they could change at any time.

Cardhop 1 0 4 – Manage Your Contacts Address Book List

Client applications must use HTTPS, and OAuth 2.0 authentication must beprovided for the user's Google account. The CardDAV server will notauthenticate a request unless it arrives over HTTPS with OAuth 2.0authentication of a Google account, and your application is registered onDevConsole. Any attempt to connect over HTTP with Basic authentication or withan email/password that doesn't match a Google account results in an HTTP401 Unauthorized response code.

To use CardDAV, your client program must initially connect to the canonicaldiscovery path by performing an HTTP PROPFIND on:

Once redirected (HTTP 301) to an Address Book Resource, your client programcan then perform a PROPFIND on it to discover theDAV:current-user-principal, DAV:principal-URL, and addressbook-home-setproperties. Your client program can then discover the principal address book byperforming a PROPFIND on the addressbook-home-set and looking for theaddressbook and collection resources. A full description of this processis beyond the scope of this document. Seerfc6352 for more details.

The redirect path returned in the HTTP 301 response through a PROPFIND onthe well-known URI must not be permanently cached (as per rfc6764). Devices should retry well-known URIdiscovery periodically to verify if the cached path is still up to date andresync if the path ever changes. Google recommends a rate of every 2-4 weeks.

Resources

CardDAV uses REST concepts. Client applications act on resources that aredesignated by their URIs. The current URI structure is specified here to helpdevelopers understand the concepts in the following section. The structure maychange and must not be hardcoded. Rather, the resources should be discoveredaccording to the RFC.

  1. Principal
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Home Set
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. Address Book
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. Contact
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Cardhop 1 0 4 – Manage Your Contacts Address Bookmarks

Synchronizing Contacts

Cardhop 1 0 4 – Manage Your Contacts Address Books

The following is a general description of the operations supported. Developersshould look for the details in the relevant RFC. Requests and responses aremostly encoded in XML. These are the main operations used by clientapplications for synchronization:

Cardhop 1 0 4 – Manage Your Contacts Address Booking

  • Using CTag
    • Client programs use the getctagPROPFIND request on the Address Bookresource to determine if any contact has changed on the server andtherefore whether a synchronization is needed. The value of this propertyis guaranteed to change if any contact changes. Client applicationsshould store this value and use it only on the initial sync and as afallback when a sync-token is invalidated. Periodically polling for thegetctag property will result in throttling.
  • Using sync-token
    • Client programs use the sync-tokenPROPFIND request on the AddressBook to obtain the sync-token representing its current state. Clientapplications must store this value and issue periodic sync-collectionREPORT requests to determine changes since the last issuedsync-token. Issued tokens are valid for 29 days, and the REPORTresponse will contain a new sync-token.
  • Using ETags
    • Client applications issue a getetagPROPFIND request on the AddressBook resource (with DEPTH header equal to DEPTH_1). By maintainingthe ETag value of each contact, a client program can request the valueof contacts that had their ETag changed.
  • Retrieving contacts
    • Client applications retrieve contacts by issuing anaddressbook-multigetREPORT request. Given a list of contact URIs,the report returns all the requested contacts as VCard 3.0 values. Eachentry includes an ETag for the contact.
  • Inserting a contact
    • Client applications issue a POST request with the new contact in VCard3.0 format. The response will contain the ID of the new contact.
  • Updating a contact
    • Client applications issue a PUT request with the updated contact inVCard 3.0 format. The contact is updated if the contact already existsin the address book.
    • Client applications should include an If-Match header with thecontact's currently known ETag. The server will then reject the PUTrequest (with HTTP 412) if the current ETag on the server isdifferent from the ETag sent by the client program. This allows foroptimistic serialization of updates.
  • Deleting a contact
    • Client applications delete a contact by issuing a DELETE requestagainst the contact URI.