Protocol Basics

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google 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, see Google 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 the Developer's Guide overview page and the Protocol 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-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.

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 on Using 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-specific samples and client 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 HTTP ETag.

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' 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>

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 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>

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 a PUT request, with the updated entry in the message body, to the entry's edit URI. The edit URI appears in the previous example as the href 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 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>

Note: 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

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

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.

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 a partial response, use the fields query parameter to specify which elements or attributes you want returned. For more information, see Partial 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 the fields parameter with any kind of request that returns data. In addition to GET, this includes POST, and PUT (as well as PATCH, which is used for making partial update requests).

Note: The fields 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 a PUT, POST, or PATCH request.

Examples for POST and PUT are shown below.

• When you make a POST request for a partial response, you must still provide the same data as described in Inserting 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 a PUT request for a partial response, you must still provide a modified version of the full resource representation, as described in Updating 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 a PATCH request to the same edit URI you use with PUT. The data that you send with PATCH 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 with PUT, you have to specify the original entry's ETag, to make sure you don't overwite anyone else's changes.

For more information on PATCH and its semantics, see Partial 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 a PATCH request, it first removes any fields specified by the entry's gd: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 of PATCH are to merge 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 the gd: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 no gd:fields attribute, no fields are removed. However, the new values for the <title> and <author> elements are merged with the target resource:

• Because Atom allows only one title per entry, the new title overwrites the existing value. 
• Because Atom allows multiple authors per entry, the new author is appended to the list of author elements already in the target resource.
  

  Note: Not all APIs conform to the Atom standard. For example, some APIs allow only a single <author> element per entry; others inherit the entry author from the feed level, making the field read-only.

After the server processes a valid PATCH request, it returns an HTTP 200 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 the fields query parameter with PATCH to request a partial response.

Additional resources

You may find the following third-party documents useful:

• Overview of Atom from IBM
• HTTP 1.1 method definitions; specification for GET, POST, PUT, and DELETE
• HTTP 1.1 status code definitions
• How to Create a REST Protocol
• Building Web Services the REST Way
• A Technical Introduction to XML
• XML Namespaces by Example

Back to top