Google Data APIs Protocol Basics

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

For more information about the Google Data APIs, see the Google Data Developer's Guide document and the Reference Guide.

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-specific client 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 the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional 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.

Examples

The following examples show bare Data API protocol requests you might send to a generic service, and the results you might receive. For examples of how to send the requests using various programming languages, see the language-specific samples and client libraries. For information about using the Google Data APIs 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 request to the server:

GET /myFeed

The server responds:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

Inserting a new entry

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

POST /myFeed

<?xml version="1.0"?>
<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 your POST 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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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 a GET request with the q parameter. For more information about query parameters, see Query requests in the protocol reference document.

GET /myFeed?q=This

The server responds with all the entries that match the search string This. (In this case there's only one.)

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

Updating an entry

To update an existing entry, use PUT, with the entry's edit URI (as provided by the server in the previous example, in the <link rel="edit"> element).

If your firewall does not allow PUT, then do an HTTP POST and set the method override header as follows:

X-HTTP-Method-Override: PUT

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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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 edit URI has changed; it now ends with "/2/" instead of "/1/". The final number in the edit URI is a version number. For more information about versions, see the Optimistic concurrency 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

Deleting an entry

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

If your firewall does not allow DELETE, then do an HTTP POST and set the method override header as follows:

 X-HTTP-Method-Override: DELETE

The following example deletes an entry:

DELETE /myFeed/1/2/

The server responds:

200 OK

Do another GET to see that the feed now contains no entries:

GET /myFeed

The server responds:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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, see HTTP status codes in the protocol reference document.

Additional resources

You may find the following third-party documents useful:

Back to top