Protocol Basics

  • This document provides basic information about the Google Data Protocol, an older API standard, and is only relevant to the APIs listed in the Google Data APIs directory.

  • The document describes the general XML format and protocol used by Google Data APIs, including examples of queries and results.

  • Understanding XML, namespaces, syndicated feeds, and standard HTTP methods (GET,POST,PUT,DELETE) is assumed for the audience of this document.

  • Examples illustrate how to request a feed, insert, search, update, and delete entries using HTTP requests with XML-based responses.

  • Partial response and partial update features, allowing for requesting and updating specific fields, are also discussed as experimental features.

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in theGoogle Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, seeGoogle Accounts Authentication and Authorization.

This document describes the basics of the Google Data Protocol used by many Google APIs, including examples of what a query looks like, what results look like, and so on.

For more information about the Google Data Protocol, see theDeveloper's Guide overview page and theProtocol Reference.

Audience

This document is intended for anyone wanting to understand the general idea of the XML format and protocol used by the Google Data APIs.

Even if you just want to write code that uses the language-specificclient libraries, you might want to read this document, to understand what's going on beneath the client-library abstraction layer.

This document assumes that you understand the basics of XML, namespaces, syndicated feeds, and theGET,POST,PUT, andDELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see theAdditional resources section of this document.

This document doesn't rely on any particular programming language; your client can interact with the server using any programming language that lets you issue HTTP requests and parse XML-based responses.

If you want to try the examples in this document without writing any code, you may find the command-line utilities cURL or Wget useful; for more information, see the manual pages for those utilities or the document onUsing cURL to interact with services that use the Google Data Protocol.

Examples

The following examples show HTTP requests you might send to a generic service using the Google Data Protocol API protocol directly, and the results you might receive. For examples of how to send the requests using various programming languages, see the language-specificsamples andclient libraries. For information about using the Google Data Protocol with specific Google services, see the service-specific documentation.

Requesting a feed or other resource

Assume there's a feed called /myFeed, and assume that it currently doesn't happen to contain any entries. To see it, send the following HTTP request to the server:

GET /myFeed

The server responds:

200 OK<?xml version='1.0' encoding='utf-8'?><feed xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>  <title>Foo</title>  <updated>2006-01-23T16:25:00-08:00</updated>  <id>http://www.example.com/myFeed</id>  <author>    <name>Jo March</name>  </author>  <link href='/myFeed' rel='self'/></feed>

Note that although the feed doesn't contain any entries, it does contain metadata, such as a title and an author's name. It also contains a version identifier, in the form of an HTTPETag.

Inserting a new entry

To create a new entry, send aPOST request, and supply the XML representation of the new entry:

POST /myFeed<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'>  <author>    <name>Elizabeth Bennet</name>    <email>liz@gmail.com</email>  </author>  <title type='text'>Entry 1</title>  <content type='text'>This is my entry</content></entry>

Note that you don't supply the standard Atom<id>,<link>, or<updated> elements; the server creates those in response to yourPOST request. Also note that the author of a feed doesn't have to be the same person as the author of an entry.

The server responds:

201 CREATED<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>  <id>http://www.example.com/id/1</id>  <link rel='edit' href='http://example.com/myFeed/1/1/'/>  <updated>2006-01-23T16:26:03-08:00</updated>  <author>    <name>Elizabeth Bennet</name>    <email>liz@gmail.com</email>  </author>  <title type='text'>Entry 1</title>  <content type='text'>This is my entry</content></entry>

Searching for a string

To do a full-text search for a particular string, when using a service that supports full-text searches, send aGET request with theq parameter. For more information about query parameters, seeQuery requests in the protocol reference document.

GET /myFeed?q=This

The server responds with a feed containing all the entries that match the search stringThis. (In this case there's only one.)

200 OK<?xml version='1.0' encoding='utf-8'?><feed xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>  <title>Foo</title>  <updated>2006-01-23T16:26:03-08:00</updated>  <id>http://www.example.com/myFeed</id>  <author>    <name>Jo March</name>  </author>  <link href='/myFeed' rel='self'/>  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>    <id>http://www.example.com/id/1</id>    <link rel='edit' href='http://example.com/myFeed/1/'/>    <updated>2006-01-23T16:26:03-08:00</updated>    <author>      <name>Elizabeth Bennet</name>      <email>liz@gmail.com</email>    </author>    <title type='text'>Entry 1</title>    <content type='text'>This is my entry</content>  </entry></feed>

Updating an entry

To update an existing entry, you need to do the following steps.

  1. Retrieve the entry you want to update.
  2. Modify it as desired.
  3. Send aPUT request, with the updated entry in the message body, to the entry's edit URI. The edit URI appears in the previous example as thehref attribute of the<link rel='edit'> element.

You also have to specify the original entry's ETag, to ensure that you don't overwrite anyone else's changes.

In the following example, we're changing the entry's text from its old value ("This is my entry") to a new value ("This is my first entry."):

PUT /myFeed/1/1/<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>  <id>http://www.example.com/id/1</id>  <link rel='edit' href='http://example.com/myFeed/1/'/>  <updated>2006-01-23T16:28:05-08:00</updated>  <author>    <name>Elizabeth Bennet</name>    <email>liz@gmail.com</email>  </author>  <title type='text'>Entry 1</title>  <content type='text'>This is my first entry.</content></entry>

The server responds:

200 OK<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>  <id>http://www.example.com/id/1</id>  <link rel='edit' href='http://example.com/myFeed/1/'/>  <updated>2006-01-23T16:28:05-08:00</updated>  <author>    <name>Elizabeth Bennet</name>    <email>liz@gmail.com</email>  </author>  <title type='text'>Entry 1</title>  <content type='text'>This is my first entry.</content></entry>

Note that the ETag has changed. For more information about versions of resources, see theResource versioning (ETags) section of the protocol reference document.

To see the new entry in context, request the entire resource again:

GET /myFeed

The server responds:

200 OK<?xml version='1.0' encoding='utf-8'?><feed xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>  <title>Foo</title>  <updated>2006-01-23T16:28:05-08:00</updated>  <id>http://www.example.com/myFeed</id>  <author>    <name>Jo March</name>  </author>  <link href='/myFeed' rel='self'/>  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>    <id>http://www.example.com/id/1</id>    <link rel='edit' href='http://example.com/myFeed/1/'/>    <updated>2006-01-23T16:28:05-08:00</updated>    <author>      <name>Elizabeth Bennet</name>      <email>liz@gmail.com</email>    </author>    <title type='text'>Entry 1</title>    <content type='text'>This is my first entry.</content>  </entry></feed>

Note: If your firewall does not allowPUT, then do an HTTPPOST and set the method override header as follows:

X-HTTP-Method-Override: PUT

Deleting an entry

To delete an existing entry, send aDELETE request, using the entry's edit URI (as provided by the server in the previous example).

If your firewall does not allowDELETE, then do an HTTPPOST and set the method override header as follows:

X-HTTP-Method-Override: DELETE

When you delete an entry, you can choose whether to do a conditional delete (only delete if the entry hasn't changed since last time you retrieved it) or an unconditional delete. For more information, see theResource versioning (ETags) section of the protocol reference document. To do an unconditional delete, set the following HTTP header:

If-Match: *

The following example deletes an entry (if headers are set appropriately):

DELETE /myFeed/1/

The server responds:

200 OK

Do anotherGET to see that the feed now contains no entries:

GET /myFeed

The server responds with a feed that contains nothing but metadata:

200 OK<?xml version='1.0' encoding='utf-8'?><feed xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>  <title>Foo</title>  <updated>2006-01-23T16:30:11-08:00</updated>  <id>http://www.example.com/myFeed</id>  <author>    <name>Jo March</name>  </author>  <link href='/myFeed' rel='self'/></feed>

If the deletion fails, then the server responds with an error code. For more information, seeHTTP status codes in the protocol reference document.

Requesting partial feeds or entries(Experimental)

In contrast to the simple example feed shown in this document, in practice, feeds can be quite complex. With some APIs, you can ask for only the elements or attributes of interest, instead of the full resource representation. When you avoid retrieving and parsing unneeded data, you can significantly improve the efficiency of your client application.

To request apartial response, use thefields query parameter to specify which elements or attributes you want returned. For more information, seePartial response in the protocol reference document.

The following example requests only the feed ID, and the author and title for each feed entry,

GET /myFeed?fields=id,entry(author)

The server responds:

200 OK<?xml version='1.0' encoding='utf-8'?><feed xmlns='http://www.w3.org/2005/Atom'  xmlns:gd='http://schemas.google.com/g/2005'>  <id>http://www.example.com/myFeed</id>  <entry>    <author>      <name>Elizabeth Bennet</name>      <email>liz@gmail.com</email>    </author>    <title type='text'>Entry 1</title>  </entry>  <entry>    <author>      <name>Elizabeth Bennet</name>      <email>liz@gmail.com</email>    </author>    <title type='text'>Entry 2</title>  </entry></feed>

You can use thefields parameter with any kind of request that returns data. In addition toGET, this includesPOST, andPUT (as well asPATCH, which is used for makingpartial update requests).

Note: Thefields query parameter only controls the data sent back in response to a request; it does not affect the data that you must provide in the body of aPUT,POST, orPATCH request.

Examples forPOST andPUT are shown below.

  • When you make aPOST request for a partial response, you must still provide the same data as described inInserting a new entry. The following example requests a partial response that contains only the title of the newly created entry:
    POST /myFeed?fields=title      ...data...

    The server responds:

    200 OK<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'>  <title type='text'>Entry 1</title></entry>
  • When you make aPUT request for a partial response, you must still provide a modified version of the full resource representation, as described inUpdating an entry. The following example requests a partial response that contains only the new ETag value of the modified entry:
    PUT /myFeed/1/1?fields=@gd:etag  ...data...

    The server responds:

    200 OK<?xml version='1.0' encoding='utf-8'?><entry xmlns='http://www.w3.org/2005/Atom'  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Updating specific fields(Experimental)

If the API you are using supports partial response and has editable fields, you can also avoid sending unnecessary data when modifying an entry.Partial update allows you to send data only for the fields that you want to change.

To use partial update, you send aPATCH request to the same edit URI you use withPUT. The data that you send withPATCH must follow certain conventions. However, the semantics are flexible enough for you to replace data in the target resource, add to it, or even make deletions from it, all with a single request.

Note: As withPUT, you have to specify the original entry's ETag, to make sure you don't overwite anyone else's changes.

For more information onPATCH and its semantics, seePartial update in the protocol reference document.

This example shows a partial update request that modifies the entry's title:

PATCH /myFeed/1/1/<entry xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:etag="EksPTg1Bfyp7IWA6WhJT"    gd:fields='title'>  <title>New Title</title></entry>

When the server receives aPATCH request, it first removes any fields specified by the entry'sgd:fields attribute (if present); then it merges any data provided in the request body with the target resource. In this example, the title element is first removed from the target resource; then the new title value is merged. Effectively, this request replaces the old title with the new one.

Note, however, that the semantics ofPATCH are tomerge the partial representation into the existing resource. You don't always have to remove a field to update its value.

  • If the field can only exist once in the target entry then, on merging, the field in the partial representation overwrites the corresponding field in the target entry.
  • If the field can exist more than once in the target entry then, on merging, the partial field is added to the target entry.

The difference between how repeating and non-repeating fields are merged is shown by the next example, which adds a new title and author to the entry without using thegd:fields attribute to remove either of them first.

PATCH /myFeed/1/1/<entry xmlns='http://www.w3.org/2005/Atom'    xmlns:gd='http://schemas.google.com/g/2005'    gd:edtag="EksPTg1Bfyp7IWA6WhJT">  <title>A new title</title>  <author>    <name>Fitzwilliam Darcy</name>    <email>darcy@gmail.com</email>  </author></entry>

Since the partial entry representation has nogd:fields attribute, no fields are removed. However, the new values for the<title> and<author> elements are merged with the target resource:

After the server processes a validPATCH request, it returns an HTTP200 status code, along with a copy of the full representation of the updated entry.

If you prefer to have the server return only certain elements or attributes, you can use thefields query parameter withPATCH to request apartial response.

Additional resources

You may find the following third-party documents useful:

Back to top

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2023-11-03 UTC.