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 APIs Overview document and the Protocol Reference document.
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.
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.
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 HTTP ETag.
To create a new entry, send a POST 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 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' 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>
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 a feed containing all the entries that match the search string This. (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>
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
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 the Resource 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>
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
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 the Resource 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 another GET 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, see HTTP status codes in the protocol reference document.
You may find the following third-party documents useful:
GET, POST, PUT, and DELETE