My favorites | English | Sign in

Try Google Chrome's developer tools New!

Google Contacts Data API

Contacts Data API Version 2 Migration Guide

Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.

This guide explains what you need to do to migrate your existing client applications from version 1 to version 2 of the Contacts Data API.

This guide contains information specific to the Contacts Data API. For more general information about migrating Data API clients, see the Google Data APIs Migration Guide.

Contents

  1. Audience
  2. Migrating to version 2
  3. Updating a Java client
  4. Updating a protocol-based client

Audience

This guide is intended for developers who have written a client under version 1 of the Contacts Data API and want to update it to work with version 2.

If you haven't written a client under version 1, then you can ignore this guide; just read the regular version 2 developer's guide.

Migrating to version 2

To update your version 1 client to version 2, here's what you need to do:

  • If you used the .NET, JavaScript, or Python client libraries, those client libraries don't yet support version 2, so you can't update your client yet.
  • If you used the Java client library, then download and use the latest version of the client library. Most of your code will still work, and the client library takes care of the version 2 changes under the hood. For specific things you have to update in Java, see Updating a Java client, below.
  • If you used the raw HTTP and XML protocol, then update your client as described below in Updating a protocol-based client.

Updating a Java client

To update your Java client:

  • If your client uses ContactsService.delete to delete entries, change it to use ContactEntry.delete instead.
  • Code for adding, updating, and deleting photos needs to be changed. For details, see the Java section of the developer's guide.

Updating a protocol-based client

To update your client if you used the raw protocol:

  • Add an HTTP version header (GData-Version: 2) to every HTTP request you send. Alternatively, add a query parameter (v=2) to the URL of every request.
  • Change your update and delete code to use ETags. For more information, read the ETags section of the Google Data API documentation, and read the Update and Delete sections of the Contacts Data API Protocol developer's guide.
  • If your client keeps track of self or edit URIs for feeds or entries, note that those URIs may have changed. To get the new URI, re-request the item using the old URI, but mark the request as a version 2 request (by, for example, appending the v=2 query parameter to the URI). The server returns the version 2 representation of the entry, including the new URIs, which you can store in place of the old ones.
  • If your client stores Data API namespace URIs locally, or has them hard-coded, you'll need to update them:
    • The AtomPub namespace (prefix app) has been changed from http://purl.org/atom/app to http://www.w3.org/2007/app.
    • The OpenSearch namespace (prefix openSearch) has been changed from http://a9.com/-/spec/opensearchrss/1.0/ to http://a9.com/-/spec/opensearch/1.1/.
  • The edit-photo links from version 1 no longer exist in version 2. Instead, use the photo link (with rel value of http://schemas.google.com/contacts/2008/rel#photo), which is now always present. If a photo exists, then it has a gd:etag attribute; to update or delete the photo, pass the ETag in the If-Match header. For details, see Contact photo management in the Developer's Guide.
  • More than one contact can now have the same email address, so Google no longer returns a 409 Conflict status code if you try to create a new contact with the same email address as another contact. Thus, if your client relies on this behavior, you may need to change your client to check for existing contacts with the given address before creating a new one.
  • After updating your client to use version 2, perform a full synchronization with the server, even if the client usually performs incremental synchronizations using the updated-min query parameter. This provides your client with ETags and the new photo links, as well as indicating which contacts belong to which system groups. If you don't do a full synchronization, then the server won't tell you that the contacts have been put in system groups, because from the server's point of view, the contacts haven't changed.
  • In version 1, when you created a new contact, it was implicitly added to the My Contacts system group, which was visible only in the GMail contacts GUI. (This wasn't documented, but some developers may have discovered it.) In version 2, if you want to place a new contact in the My Contacts group, you must do so explicitly, by adding an appropriate <gContact:groupMembershipInfo> element to the contact.

Back to top