Google Documents List Data API

Documents List Data API
- Developer's Guide
- - Version 3.0 ^(Labs ⁾
  - Version 2.0
  - Version 1.0
    - Protocol Guide
    - Reference Guide
    - Java
    - .NET
    - PHP
    - Python
- API Changelog
- Libraries and Code
- Solutions Marketplace

Google Data Protocol

API Changelog

Google periodically updates the Documents List Data API in order to deliver new features and to repair defects discovered in previous versions. In most cases, these changes will be transparent to API developers. However, occasionally we need to make changes that require developers to modify their existing applications.

This page documents any changes made to the Documents List API that may effect your application. We recommend that API developers periodically check this list for any new announcements. Changes will also be announced via this page's Atom feed and the Documents List API discussion group.

Release 2009-09 (September 28, 2009)

This release introduces new functionality to v3.0.

New Features & Changes:

OCR for .gif, .jpg, and .png upload.
Document translation service on doc upload.
Key based pagination.

By default the doclist will now return 100 documents (instead of all the user’s documents). This saves bandwidth and improves performance. To specify more than 100 documents, use the max-results=x parameter, where x is a cap for the # of documents you wish to return. For example, using max-results=50 may return 1-50 documents. You can then page through results by following the ‘next’ link in each returned <feed>.
Export servlets now support the full <gd:resourceID> as the docID or key parameter. Example: /feeds/download/documents/Export?docID=document:12345&exportFormat
Removed <openSearch:startIndex> and <openSearch:itemsPerPage>.

Fixes in this release:

Fixed HTTPS (SSL) wasn’t being respected for PDF downloads Issue 1448
Fixed querying legacy folder ids returning a 400 in v2.0 Issue 1482

Release Version 3.0 (August 25, 2009)

This release introduces substantial new functionality and backwards incompatible changes to the existing API. It also deprecates certain features (listed below). As such, we’re moving to a new major version (version 3.0). It should be assumed that any features deprecated in v3 will continue to work under previous versions and be supported for 3 years.

Major Features:

Better feed URI formats. See the reference guide.
PDF Upload and Download: Issues 591, 1132
Document Revision History Issue 923
Ability to delete a document Issue 1368
Folder sharing
Group and domain-level sharing
Added edited-min and edited-max parameters. See the reference guide.

API error responses are now wrapped in XML output. Example:

  <errors xmlns="http://schemas.google.com/g/2005">
    <error>
      <domain>GData</domain>
      <code>invalidRequestUri</code>
      <internalReason>Invalid request URI</internalReason>
    </error>
  </errors>

Deprecations:

Folders Category Scheme In V2, for every folder a document is in, the <atom:entry> for the document contains a category of the form:

<category scheme="http://schemas.google.com/docs/2007/folders/user@gmail.com" term="foldername" label="foldername"/>

In V3, this category scheme was removed as the same information may be retrieved via the parent link on the <atom:entry>:

<link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/folder%3Afolder_id" title="foldername"/>

V2 Support: The category will continue to be added in older versions of the API.
Query By Folder Name

As a consequence of the folders category scheme above, in V2 it is possible to query for documents by folder name via:

GET /feeds/documents/private/full/-/foldername

In addition, category filters can be combined an any arbitrary fashion with logical operators so it is possible to query for documents which are in a folder named A or B but not C. In V3, this functionality was removed as the corresponding category scheme will no longer exist.

V2 Support: This feature will remain when the resulting document list is less than 500 documents.
Index Based Paging

The standard way to page Google Data requests is via start-index and max-results query parameters:

GET /feeds/documents/private/full/?start-index=10&max-results=20

This does not scale for large numbers of documents. As a result, the start-index parameter will no longer be supported. Instead, the doclist <feed> will contain a ‘next’ link pointing to the next set of paged results.

V2 Support: This feature will remain when the resulting document list is less than 2000 documents.
OpenSearch Elements

The API supports an <openSearch:totalResults> element which is the total number of results which match a given query. This does not scale for large numbers of documents and therefore this element was removed in V3.

V2 Support: This feature will remain when the resulting document list is less than 2000 documents.
Sorting

V2 feed results can be sorted based on title, starred, last-modified, and last-viewed. Due to backend complications, the default sort order will be last-modified. The option to specify other sorting orders was removed in V3.

V2 Support: This feature will remain when the resulting document list is less than 2000 documents.
Stemming / etc. Features in Search.

It is currently documented as part of the standard Google Data query parameters that a full text search (q paramater) does stemming. For example, a search for ‘enable’ will match ‘enabled’. This will no longer be the case.
Append to a Document

It was decided that the API should not handle content manipulation other than full document uploads/replacements so the ability to append to document was removed from v3 (e.g. the ?append=true parameter is gone).

V2 Support: V2 will continue to support this functionality.