Developer's Guide Overview

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.

The Google Data Protocol provides a secure means for external developers to write new applications that let end users access and update the data stored by many Google products. External developers can use the Google Data Protocol directly, or they can use any of the supported programming languages provided by the client libraries.

Audience

This set of documents is intended for anyone who wants to understand Google Data Protocol. Even if you just want to write code that uses the language-specific client libraries, this document set can be helpful if you want to understand what's going on beneath the client-library abstraction layer.

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

If you want to access an API in your favorite programming language, visit the Client Libraries download page.

Background

A number of Google products, such as Calendar and Spreadsheets, provide APIs that are based on the Google Data Protocol. You, the developer, can use these APIs to write client applications that give end users new ways to access and manipulate the data they store in those Google products.

Note: Google products that provide APIs are sometimes referred to as services in these and other related documents.

If you write code that uses the Google Data Protocol directly, it accesses the API using HTTP requests like GET or POST. With these requests, data stored by the Google product is transferred back and forth over the wire in the form of data feeds. The data feeds are simply structured lists that contain the data. Historically, the primary feed format has been AtomPub XML, but now JSON, or JavaScript Object Notation, is also available as an alternate format.

If you prefer not to write code that makes HTTP requests directly, you can instead program your client application using one of the programming languages available in the set of client libraries provided. When you do this, the details of the HTTP requests are handled by the client library; you write your code at a more conceptual level using the language-specific methods and classes provided by the client library.

Refer to the product-specific documentation for more information about the particular languages available for the API, or API version, you are using.

Versions of the protocol

Protocol Version 2.0 vs. Protocol 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.

The Google Data Protocol Version 2.0 also includes support for:

• HTTP ETags. A web standard that helps your client applications make better use of HTTP caching. The services included in the client libraries that support Protocol v2.0 handle ETags automatically.
• Partial Response and Partial Update (Experimental). Features that let you make requests that transfer less data. By requesting only the information that you actually need, or by sending updates that include only the data that you actually want to change, your client application can be much more efficient in its use of network, CPU, and memory resources. Currently, partial response and partial update are available only for some products; see the product-specific documentation to find out if your API supports it.

Updating your application

If the API you are using was built upon the latest version of the protocol, then the Protocol v2.0 functionality is included in its documentation. In general, we recommend that you upgrade your client application to the latest version available for your API.

Updating a client-library-based client

If your client application uses a client library, such as the Java client library or the .NET client library, it may contain a version of the API that supports Protocol v2.0 features. To find out, refer to the API documentation for the Google product you are using to find out if both of the following are true:

• There is an API version that supports Google Data Protocol v2.0 features.
• The client library you are using also supports that API version.

If the client library supports it and you want to update your existing application, just download and use the latest version of the client library. All of your code still works, and the client library takes care of the Protocol v2.0 changes under the hood.

Updating a raw HTTP client

If you wrote your client application using the Google Data Protocol directly, you need to make these changes:

• Non-default version requests. Add an HTTP version header (GData-Version: X.0) to every HTTP request you send, where X is the version of the API that supports Google Data Protocol v2.0 features. Alternatively, add a query parameter (v=X.0) to the URL of every request, where X is, again, the correct version of the API. If you do not specify a later version, your requests are sent to the earliest supported version of the API by default.
• Optimistic concurrency. If you were using a version of an 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 Protocol reference documentation, and read the Update and Delete sections of the Protocol developer's guide for the service your client application is using.
• Self or edit URIs. 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 X.0 request, where X is the version of the API that supports Google Data Protocol v2.0 features. The server returns the new representation of the entry, including the new URIs, which you can store in place of the old ones.
• Namespace URIs. If your client stores Google Data Protocol 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/.