Contacts Data API Version 3 Migration Guide

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

If you're migrating from version 1, you may also be interested in the document describing how to migrate from version 1 to version 2.

Contents

Audience

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

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

Migrating to version 3

To update your version 2 client to version 3, 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 3, 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 will be using version 3 under the hood. However, you do need to make a few changes. For example, your client needs to switch from using the old unstructured name and address classes to using the new structured ones. Also, a whole slew of new fields and new types of existing fields have been added, and most applications need to provide support for them. 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 application stores contacts (or contact groups) locally, then your application must refresh its local storage from the server, for two reasons: to obtain values of the new fields exposed in the 3.0 version of the API, and to obtain the new values of the ETags, which are necessary to update the contacts (groups) afterwards.
• If the application stores contacts locally, then take care to properly store all the new elements and attributes.
• Replace the uses of ContactEntry.setTitle (and getTitle) with appropriate uses of ContactEntry.setName(Name name). Note that the Name is not a simple string, but a whole structure consisting of several name components, so in reality the necessary adaptations will be more complex.
• Replace all the uses of ContactEntry.getPostalAddresses (hasPostalAddresses, and addPostalAddress) with appropriate uses of ContactEntry.getStructuredPostalAddresses (hasStructuredPostalAddresses, addStructuredPostalAddress). The old methods operate on the PostalAddress class, while the new ones operate on the StructuredPostalAddress. The PostalAddress essentially contains a single text value, while the StructuredPostalAddress is a more complex structure consisting of several address components, so in reality the necessary changes will be more complex.

Regardless of the way in which you're going to access the Contacts Data API 3.0, you should consult the section on older versions and structured data.

Updating a protocol-based client

To update your client if you used the raw protocol:

• Add an HTTP version header (GData-Version: 3.0) to every HTTP request you send. Alternatively, add a query parameter (v=3.0) to the URL of every request.
• If your application stores contacts (or contact groups) locally, the contacts will have to be refreshed from the server. This has to be done for two reasons: to obtain values of the new fields exposed in the 3.0 version of the API, and to obtain the new values of the ETags, which are necessary to update the contacts (groups) afterwards.
• Replace the uses of atom:title in contact entries by uses of gd:name. Take into account that the latter is not a simple string value, but rather a complex structure consisting of various name components.
• Replace the uses of gd:postalAddress in contact and contact group entries by uses of gd:structuredPostalAddress. Take into account that the latter is not a simple string value, but rather a complex structure consisting of various address components.

Older versions and structured data

Contacts Data API versions prior to 3.0 use the atom:title element to represent the contact's name, and gd:postalAddress for representing postal addresses associated with the contact. Both of these elements were simple, unstructured strings.

The 3.0 version introduces structured name (gd:name) and structured postal address (gd:structuredPostalAddress) as replacements. As clients of the old versions of the API and the new version essentially operate on the same data set, their coexistence gives rise to some unobvious interactions.

The value of atom:title as seen and manipulated by pre-3.0 clients is seen by 3.0 clients as the gd:fullName subelement of gd:name (gd:name/gd:fullName in the XPath notation). Whenever a 3.0 client modifies gd:name/gd:fullName, an older client is able sees the change reflected in atom:title.

A more interesting situation takes place when a pre-3.0 client modifies atom:title. Because such clients are not aware of all the detailed fields of the structured name, they do not provide a value for e.g. gd:name/gd:givenName. Under these circumstances, the server may attempt to guess the structured name components by parsing the unstructured name. Such parsing is necessarily heuristic, and the results may not be satisfactory in all cases.

Analogously, the value of pre-3.0 gd:postalAddress is reflected in the 3.0 API's gd:structuredPostalAddress/gd:formattedAddress. Modifications of gd:structuredPostalAddress/gd:formattedAddress are seen by old clients as modifications of gd:postalAddress. Modifications of gd:postalAddress by old clients are reflected in the gd:formattedAddress, and they may also trigger heuristic parsing with the goal of obtaining the remaining components of gd:structuredPostalAddress.

Even if your application only uses one "flavor" of names/addressed (either formatted or structured), it still must be prepared to encounter contacts that contain the other flavor only. In particular, there are many contacts that only have gd:fullName and gd:formattedAddress present. More details on this subject can be found in the Developer's Guide.

Back to top