# 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](https://developers.google.com/gdata/docs/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](https://developers.google.com/accounts).

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](https://developers.google.com/gdata/docs/developers-guide) overview page and the [Protocol Reference](https://developers.google.com/gdata/docs/2.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/docs/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](https://developers.google.com/gdata/docs/2.0/basics#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](https://developers.google.com/gdata/articles/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](https://developers.google.com/gdata/samples) and [client libraries](https://developers.google.com/gdata/docs/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](https://developers.google.com/gdata/docs/2.0/reference#ResourceVersioning).

### 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](https://developers.google.com/gdata/docs/2.0/reference#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)](https://developers.google.com/gdata/docs/2.0/reference#ResourceVersioning) 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)](https://developers.google.com/gdata/docs/2.0/reference#ResourceVersioning) 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](https://developers.google.com/gdata/docs/2.0/reference#HTTPStatusCodes) 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](https://developers.google.com/gdata/docs/2.0/reference#PartialResponse) 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](https://developers.google.com/gdata/docs/2.0/basics#PartialUpdate) 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](https://developers.google.com/gdata/docs/2.0/basics#InsertingEntry). 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](https://developers.google.com/gdata/docs/2.0/basics#UpdatingEntry)[](https://developers.google.com/gdata/docs/2.0/basics#UpdatingEntries). 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](https://developers.google.com/gdata/docs/2.0/reference#PartialUpdate) 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](https://developers.google.com/gdata/docs/2.0/basics#PartialResponse).

## 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/2.0/basics#top)