# 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](https://developers.google.com/gdata/docs/developers-guide) document and the [Reference Guide](https://developers.google.com/gdata/docs/1.0/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](https://developers.google.com/gdata/clientlibs), 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](https://developers.google.com/gdata/docs/1.0/basics#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](https://developers.google.com/gdata/samples) and [client libraries](https://developers.google.com/gdata/clientlibs). 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](https://developers.google.com/gdata/docs/1.0/reference#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](https://developers.google.com/gdata/docs/1.0/reference#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](https://developers.google.com/gdata/docs/1.0/reference#HTTPStatusCodes) in the protocol reference document.

# Additional resources

You may find the following third-party documents useful:

- [Overview of Atom](http://www-128.ibm.com/developerworks/xml/library/x-atom10.html) from IBM
- HTTP 1.1 [method definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html); specification for `GET`, `POST`, `PUT`, and `DELETE`
- HTTP 1.1 [status code definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
- [How to Create a REST Protocol](http://www.xml.com/lpt/a/2004/12/01/restful-web.html)
- [Building Web Services the REST Way](http://www.xfront.com/REST-Web-Services.html)
- [A Technical Introduction to XML](http://www.xml.com/pub/a/98/10/guide0.html)
- [XML Namespaces by Example](http://www.xml.com/pub/a/1999/01/namespaces.html)

[Back to top](https://developers.google.com/gdata/docs/1.0/basics#top)