Protocol Basics (original) (raw)

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

Foo 2006-01-23T16:25:00-08:00 http://www.example.com/myFeed Jo March

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

Elizabeth Bennet liz@gmail.com Entry 1 This is my 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

http://www.example.com/id/1 2006-01-23T16:26:03-08:00 Elizabeth Bennet liz@gmail.com Entry 1 This is my 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

Foo 2006-01-23T16:26:03-08:00 http://www.example.com/myFeed Jo March http://www.example.com/id/1 2006-01-23T16:26:03-08:00 Elizabeth Bennet liz@gmail.com Entry 1 This is my entry

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/

http://www.example.com/id/1 2006-01-23T16:28:05-08:00 Elizabeth Bennet liz@gmail.com Entry 1 This is my first entry.

The server responds:

200 OK

http://www.example.com/id/1 2006-01-23T16:28:05-08:00 Elizabeth Bennet liz@gmail.com Entry 1 This is my first 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

Foo 2006-01-23T16:28:05-08:00 http://www.example.com/myFeed Jo March http://www.example.com/id/1 2006-01-23T16:28:05-08:00 Elizabeth Bennet liz@gmail.com Entry 1 This is my first entry.

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

Foo 2006-01-23T16:30:11-08:00 http://www.example.com/myFeed Jo March

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

http://www.example.com/myFeed Elizabeth Bennet liz@gmail.com Entry 1 Elizabeth Bennet liz@gmail.com Entry 2

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.

...data...
The server responds:
200 OK


Entry 1

...data...
The server responds:
200 OK

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/

New Title

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.

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/

A new title Fitzwilliam Darcy darcy@gmail.com

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:

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:

Back to top