Data APIs Version 2 Migration Guide

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

Contents

Audience

This guide is intended for developers who have written a client under version 1 of the Google Data APIs 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 guides.

Migrating to version 2

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

• If you used a Data API client library, such as the Java client library or the .NET client library, just download and use the latest version of the client library. All of your code will still work, and the client libraries take care of the version 2 changes under the hood.
• If you used the raw HTTP and XML protocol, then update your client as described below.

Note: Not all client libraries have been updated to version 2 yet. For information on which client libraries have been updated, see the developer's guide landing page for the service you're working with.

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.
• If you were using a Google Data API that supported optimistic concurrency, you may need to 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 Protocol developer's guide for the service that your client interacts with.
• 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/.

Which services have changed?

The following table shows the current version number for each Data API, as of November 12, 2008. For the most up-to-date information, see the service-specific documentation.

All version 2 Data APIs are AtomPub-compliant unless specified otherwise. All version 1 Data APIs are compliant with the draft AtomPub specification and with OpenSearch 1.0.

In the following table, the "Strong ETags?" column indicates whether the service provides strong ETags on at least some entry types. (Some services may provide strong ETags for some entry types but not for others.) If a service is marked as "no" in that column, then it provides only weak ETags. Version-1 services don't support ETags at all, so they're marked "N/A".

Back to top