Google Data Protocol Developer's Guide

If you're looking for a Developer's Guide for a specific Google API, visit the API Directory.

If you're looking for access to a Google API in your favorite non-HTTP language, visit the list of Client Libraries.

Our Motivation

Google's mission is to organize the world's information and make it universally accessible and useful. This includes making information accessible in contexts other than a web browser and accessible to services outside of Google. As an end-user or a developer, you are the owner of your information, and we want to give you the best tools possible to access, manipulate, and obtain that information.

Why AtomPub?

Web syndication is an effective and popular method for providing and aggregating content. The Google Data Protocol extends AtomPub as a way to expand the types of content available through syndication. In particular, the protocol lets you use the AtomPub syndication mechanism to send queries and receive query results. It also lets you send data to Google and update data that Google maintains.

Why JSON?

JSON, or JavaScript Object notation, is a lightweight data interchange format in widespread use among web developers. JSON is easy to read and write; you can parse it using any programming language, and its structures map directly to data structures used in most programming languages. Within the Google Data Protocol, JSON objects simply mirror the Atom representation.

Versions of the Protocol

Version 2.0 vs Version 1.0

The first version of the Google Data Protocol was developed before the Atom Publishing Protocol was finalized. The second version of the Google Data Protocol is fully compliant with the AtomPub RFC 5023 standard. Version 2.0 also includes support for HTTP ETags, a web standard that helps clients make better use of HTTP caching. The services included in the client libraries that support v2.0 handle ETags automatically.

Updating a Client Library

If you used a 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 should still work, and the client libraries take care of the v2.0 changes under the hood.

Updating a Raw (HTTP) 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/.