My favorites | English | Sign in

Google Documents List Data API v1.0

Protocol Guide (v1.0)

Important: This Developer's Guide describes how to work with an older version of the Document List Data API protocol. Rest assured we will continue to support this version according to our Terms of Service. However, the latest (and we think greatest) version of the protocol can be found in the left-side navbar -- if it meets your needs, we encourage you to migrate.

Contents

  1. Audience
  2. Authenticating to the Documents service
    1. ClientLogin for "installed" applications
    2. AuthSub for web applications
    3. Upgrading to a session token
  3. Retrieving a list of documents
  4. Uploading documents
    1. Uploading content with metadata
    2. Uploading content without metadata
    3. Uploading only metadata (no content)
  5. Updating documents
    1. Updating metadata
    2. Updating content
    3. Updating both metadata and content
  6. Creating a folder
  7. Trashing a document or folder
  8. Searching the documents feed
    1. Retrieving all word processor documents
    2. Retrieving all starred presentations
    3. Retrieving all documents in a named folder
    4. Performing a text query
    5. Retrieving all documents and folders
  9. Retrieving a list of folder contents
  10. Moving documents and folders
    1. Moving into a folder
    2. Moving out of a folder
  11. Modifying Document Sharing Permissions
    1. Overview of Document Sharing (ACLs)
    2. Retrieving the ACL feed for a Document
    3. Modifying the ACL feed for a Document

Audience

This document is intended for programmers who want to write client applications that can interact with Google Documents. It provides a series of examples of basic data API interactions using raw XML/HTTP, with explanations. After reading this document, you can learn more about interacting with the API using our client libraries by reading the language-specific examples found on the other tabs at the top of this document.

For Documents List Data API reference information, see the reference guide.

This document assumes that you understand the general ideas behind the Google Data APIs protocol. Each example in this document first shows how to use the bare protocol to interact with Documents.

Authenticating to the Documents service

To request or upload documents, your client needs an authentication token. The following sections explain how to authenticate for different types of client applications.

Your choice of authentication method should be determined by the kind of client you're writing: single-user desktop applications should use the ClientLogin system, while multi-user web apps should use the AuthSub system. For a more detailed discussion of these authentication systems, see the Google Account Authentication document.

Whichever method you choose, you can either send raw HTTP requests or have Google's client libraries handle the authentication for you.

ClientLogin for "installed" applications

To authenticate the user, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

Include the relevant parameters in the body of the POST request, as described in the ClientLogin documentation. The service name for Documents is "writely".

If the request succeeds, then the response contains an alphanumeric string labeled Auth.

After a successful authentication request, use the Auth value to create an Authorization header for each request:

Authorization: GoogleLogin auth=yourAuthValue

AuthSub for web applications

To acquire an AuthSub token for a given Documents user, your application must redirect the user to the AuthSubRequest URL at Google, which prompts them to log into their Google account.

After the user logs in, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to the next URL as the value of the token query parameter. Your application then uses that authentication token in subsequent interactions with Documents.

The below example shows a request to authorize www.example.com:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fdocs.google.com%2Ffeeds%2Fdocuments&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.pyc

Upgrading to a session token

By default, the AuthSub token can only be used for one request. To receive a token which can be used for multiple requests, it must be upgraded by making an HTTP GET request which contains the single use token as an Authorization header. A token may only be upgraded if the initial AuthSub request included session=1 as a URL parameter.

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: https://www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

If the token was upgraded successfully, the server's response contains the new token information in the HTTP headers. Here's an example response:

Token=DQAA...7DCTN
Expiration=20061004T123456Z

Use the authentication token to create an Authorization header for each request:

Authorization: AuthSub token="yourAuthToken"

For details, including information on registering your application with Google and other topics, see the AuthSub documentation.

Note: The token value in the Authorization header should be surrounded by quotation marks.

Retrieving a list of documents

You can get a feed containing a list of the currently authenticated user's documents by sending an authenticated GET request to the following URL:

http://docs.google.com/feeds/documents/private/full

The result is a feed that lists all of that user's documents; each entry in the feed represents a document associated with the user. This feed is accessible only using an authentication token.

Entries in the Documents List feed might look something like the following:

<entry>
  <content src="http://spreadsheets.google.com/fm?fmcmd=102&key=key"
  type="text/html" />
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <category label="spreadsheet"
  scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/docs/2007#spreadsheet" />
  <category label="My Favorite Spreadsheets"
  scheme="http://schemas.google.com/docs/2007/folders/user_email"
  term="My Favorite Spreadsheets" />
  <id>http://docs.google.com/feeds/documents/private/full/spreadsheet%3Akey</id>
  <link href="http://spreadsheets.google.com/ccc?key=key"
  rel="alternate" type="text/html" />
  <link href="http://spreadsheets.google.com/feeds/worksheets/key/private/full"
  rel="http://schemas.google.com/spreadsheets/2006#worksheetsfeed"
  type="application/atom+xml" />
  <link href="http://docs.google.com/feeds/documents/private/full/spreadsheet%3Akey"
  rel="self" type="application/atom+xml" />
  <title type="text">Test Spreadsheet</title>
  <updated>2007-07-03T18:03:32.045Z</updated>
</entry>
<entry>
  <content src="http://docs.google.com/RawDocContents?action=fetch&docID=document_id"
  type="text/html" />
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <category label="document"
  scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/docs/2007#document" />
  <category label="starred"
  scheme="http://schemas.google.com/g/2005/labels"
  term="http://schemas.google.com/g/2005/labels#starred" />
  <id>http://docs.google.com/feeds/documents/private/full/document%3Adocument_id</id>
  <link href="http://foobar.com/Doc?id=document_id" rel="alternate"
  type="text/html" />
  <link href="http://docs.google.com/feeds/documents/private/full/document%3Adocument_id"
  rel="self" type="application/atom+xml" />
  <title type="text">Test Document</title>
  <updated>2007-07-03T18:02:50.338Z</updated>
</entry>

The first entry is a spreadsheet that is contained in a folder named "My Favorite Spreadsheets" and the second entry is a starred word processor document. Notice that their types can be distinguished by the category element with the http://schemas.google.com/g/2005#kind scheme. The spreadsheet key in the example has been replaced with key and the word processor document id has been replaced with document_id. For the spreadsheet example's folder, the user's email address has been replaced with user_email.

Uploading documents

Documents are uploaded to the server via an HTTP POST optionally using MIME multipart encoding to combine the the document contents with a Atom entry describing the document. Any combination of Atom entry and an HTTP Slug header can be used to specify the title of the uploaded document, but the following precedence will determine the final document name:

  1. The Atom entry <atom:title/> if present
  2. The HTTP Slug header value if present
  3. A default filename chosen by Google Documents

Currently you can upload word processor documents, spreadsheets and presentations. See the FAQ for a list list of accepted formats.

Uploading with metadata

Here is an example of uploading a document named test.doc on the client computer which will be called example document on Google Documents (See Uploading Docs for the precedence rules that determine this document name).

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 73612
Content-Type: multipart/related; boundary=END_OF_PART
Slug: test.doc
--END_OF_PART
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#document" />
  <atom:title>example document</atom:title>
</atom:entry>
--END_OF_PART
Content-Type: application/msword

... doc contents here ...

--END_OF_PART--

If the upload is successful, a 201 Created response will be returned along with a Atom entry describing the document on the server.

Uploading without metadata

Here is an example of uploading a spreadsheet which will be called Example Spreadsheet on Google Documents.

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 81047
Content-Type: application/vnd.ms-excel
Slug: Example Spreadsheet

... spreadsheet contents here ...

Again, if the upload is successful, a 201 Created response will be returned along with a Atom entry describing the document on the server.

Uploading only metadata (no content)

Here is an example of creating a document by uploading metadata to the server with an HTTP POST request. This will create an empty document called new document on Google Documents. 

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 288
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#document" />
  <atom:title>new document</atom:title>
</atom:entry>

Updating documents

To update a document, send an HTTP PUT request to either the edit link or the edit-media link, depending on what is to be updated. The update request can be one of three things:

  • An Atom entry describing updated document metadata in XML
  • The updated raw contents of the document
  • A MIME multipart request that contains both an Atom entry and document content

Note: Please note that your request must contain document content if you are planning to use the edit-media link.

The new document contents, which form part of the MIME multipart request, must have a content-type for which conversion is supported - for instance to update a Google Docs document with new content, it could have content-type application/msword, or content-type text/plain, but not content-type application/vnd.ms-excel. When updating a Google Docs spreadsheet however, content-type application/vnd.ms-excel would be appropriate. Content-types which are not supported by the document type being updated will result in a 400 Bad Request response.

Note: Please see the documentation for a complete list of accepted formats.

The edit and edit-media links both contain a version as part of the URL - this simply ensures that when you attempt to update the document, you are aware of the latest version, and so are not overwriting any recent changes. See Optimistic concurrency (versioning) in the Google Data reference document.

Updating metadata

Here is an example of updating a spreadsheet's metadata, but leaving its content unchanged. The spreadsheet's name will be changed to example spreadsheet. Since the request does not contain new document content, the edit link is used.

PUT /feeds/documents/private/full/spreadsheet%3Aid/version
Content-Length: 292
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#document" />
  <atom:title>example spreadsheet</atom:title>
</atom:entry>

Updating content

Here is an example of changing the content of a document, but leaving its metadata unchanged. The document's name will stay the same, but its contents will be replaced with the contents of word document test.doc. Since the request contains new document content, the edit-media link is used.

PUT /feeds/media/private/full/document%3Aid/version
Content-Length: 70581
Content-Type: application/msword
Slug: test.doc

... doc contents here ...

Updating metadata and content

Here is an example of updating both the documents metadata and content at the same time. The document's name will be updated to example document and its contents will be replaced with the contents of word document test.doc. Since the request contains new document content, the edit-media link is used.

PUT /feeds/media/private/full/document%3Aid/version
Content-Length: 73612
Content-Type: multipart/related; boundary="END_OF_PART"
Slug: test.doc
--END_OF_PART
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#document" />
  <atom:title>example document</atom:title>
</atom:entry>
--END_OF_PART
Content-Type: application/msword

... doc contents here ...

--END_OF_PART

In all of these cases, a successful update will return a 201 Updated response with an Atom entry describing the document on the server.

Creating a folder

To create a folder, send an HTTP POST request with an Atom entry containing a category element with http://schemas.google.com/g/2005#kind scheme and http://schemas.google.com/docs/2007#folder term. The folder name will be determined by the value of the atom:title element if present. If no atom:title element is submitted, a default name will be chosen.

Here is an example of creating a folder which will be called Example Folder on Google Documents.

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 384
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind" 
      term="http://schemas.google.com/docs/2007#folder" label="folder"/>
  <atom:title>Example Folder</atom:title>
</atom:entry>

If the request is successful, a 201 Created response will be returned along with a Atom entry describing the folder on the server.

Trashing documents and folders

To put a document or folder in the trash, send an HTTP DELETE request to the edit link. The edit link will have a document id and a version token represented by id and version respectively in the example below:

DELETE /feeds/documents/private/full/spreadsheet%3Aid/version

If you try to trash using a version number other than the latest one, you may receive an error; for more information, see Optimistic concurrency (versioning) in the Google Data reference document.

Searching the documents feed

You can search the Document List using some of the standard Google Data API query parameters. Categories are used to restrict the type of document (word processor document, spreadsheet) returned. The full-text query string is used to search the content of all the documents. More detailed information on parameters specific to the Documents List can be found in the Documents List Data API Reference Guide. Please note that the DocList API currently does not support excluding folders using the /category/-starred syntax.

Retrieving all word processor documents

A list of only word processor documents can be retrieved by using the document category as follows:

  GET /feeds/documents/private/full/-/document

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Retrieving all starred presentations

A list of only starred presentations can be retrieved by using the presentation and starred categories as follows:

  GET /feeds/documents/private/full/-/presentation/starred

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Retrieving all documents in a folder named "starred"

A list of only documents contained in a folder named "starred" created by the current user with email address email can be retrieved by using a scheme qualified folder category to disambiguate from a starred category query for starred documents as follows:

  GET /feeds/documents/private/full/-/{http:%2F%2Fschemas.google.com%2Fdocs%2F2007%2Ffolders%2Femail}starred

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Performing a text query

You can search the content of documents by using the q query parameter on the feed. For example, if you wanted to search a user's documents for the string "example query" you could do the following authenticated GET:

  GET /feeds/documents/private/full?q=example+query

Retrieving all documents and folders

A list of all documents and folders can be retrieved by using the showfolders parameter on the feed.

  GET /feeds/documents/private/full?showfolders=true

A more detailed description of how the q parameter works can be found on the Google Data APIs Reference Guide.

Retrieving a list of folder contents

To retrieve a list of documents in a particular folder, send an HTTP GET to the folder's feed URL:

http://docs.google.com/feeds/folders/private/full/folder%3Aid

The folder id is represented by id. The folders feed can also be queried using the query parameters defined in the Documents List Data API Reference Guide.

Entries in the Folder feed might look something like the following:

<entry>
  <id>
    http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/document%3Adhtqq9zk_18dcn86vfv
  </id>
  <published>0001-01-03T00:00:00.000Z</published>
  <updated>2008-09-02T05:42:27.203Z</updated>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/docs/2007#document" label="document"/>
  <category scheme="http://schemas.google.com/docs/2007/folders/test.user@gmail.com" term="Folder 1" label="Folder 1"/>
  <category scheme="http://schemas.google.com/docs/2007/folders/test.user@gmail.com" term="Folder 2" label="Folder 2"/>
  <title type="text">Document 1</title>
  <content type="text/html"
              src="http://docs.google.com/feeds/download/documents/RawDocContents?action=fetch&docID=dhtqq9zk_18dcn86vfv"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
        href="http://docs.google.com/feeds/documents/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae" title="Folder 1"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
        href="http://docs.google.com/feeds/documents/private/full/folder%3A0bd9c3c3-d771-4278-b71b-3f519ab36b74" title="Folder 2"/>
  <link rel="alternate" type="text/html" href="http://docs.google.com/Doc?id=dhtqq9zk_18dcn86vfv"/>
  <link rel="self" type="application/atom+xml"
        href="http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/document%3Adhtqq9zk_18dcn86vfv"/>
  <link rel="edit" type="application/atom+xml"
        href="http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/document%3Adhtqq9zk_18dcn86vfv/fkm3fybn"/>
  <link rel="edit-media" type="text/html" href="http://docs.google.com/feeds/media/private/full/document%3Adhtqq9zk_18dcn86vfv/fkm3fybn"/>
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <gd:feedLink rel="http://schemas.google.com/acl/2007#accessControlList"
                  href="http://docs.google.com/feeds/acl/private/full/document%3Adhtqq9zk_18dcn86vfv"/>
</entry>
<entry>
  <id>
    http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/folder%3A0bd9c3c3-d771-4278-b71b-3f519ab36b74
  </id>
  <published>0001-01-03T00:00:00.000Z</published>
  <updated>2008-07-31T00:36:07.091Z</updated>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/docs/2007#folder" label="folder"/>
  <category scheme="http://schemas.google.com/docs/2007/folders/test.user@gmail.com" term="Folder 1" label="Folder 1"/>
  <title type="text">Folder 2</title>
  <content type="application/atom+xml"
              src="http://docs.google.com/feeds/folders/private/full/folder%3A0bd9c3c3-d771-4278-b71b-3f519ab36b74"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
        href="http://docs.google.com/feeds/documents/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae" title="Folder 1"/>
  <link rel="alternate" type="text/html" href="http://docs.google.com/#folders/folder.0.0bd9c3c3-d771-4278-b71b-3f519ab36b74"/>
  <link rel="self" type="application/atom+xml"
        href="http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/folder%3A0bd9c3c3-d771-4278-b71b-3f519ab36b74"/>
  <link rel="edit" type="application/atom+xml"
        href="http://docs.google.com/feeds/folders/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae/folder%3A0bd9c3c3-d771-4278-b71b-3f519ab36b74/fk6cwqd4"/>
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <gd:feedLink rel="http://schemas.google.com/acl/2007#accessControlList"
               href="http://docs.google.com/feeds/acl/private/full/folder%3A0428bf9b-cc70-413b-a39b-8b0af0f3d7ae"/>
</entry>

Moving documents and folders

Documents and folders can be moved in and out of folders via the folders feed.

Moving into a folder

To either move a document into a folder or to move a folder into another folder, sent an HTTP POST request to the feed of the destination folder. The feed URL will have the folder id represented by id in the example below. The request should contain the Atom entry of the document or folder you want to move. If no atom:id is provided in the request, a new document will be created in the folder.

POST /feeds/folders/private/full/folder%3Aid HTTP/1.1
Content-Length: 384
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:id>http://docs.google.com/feeds/documents/private/full/document%3Adocument_id</atom:id>
  <atom:category scheme="http://schemas.google.com/g/2005#kind" 
      term="http://schemas.google.com/docs/2007#document" />
</atom:entry>

The entry is a word processor document with id document_id.

Moving out of a folder

To move a document or folder out of a folder, sent an HTTP DELETE request to the destination folder's edit link. The edit link will have a folder id, document id and a version token represented by id, document_id and version respectively in the example below.

DELETE /feeds/folders/private/full/folder%3Aid/document%3Adocument_id/version

Modifying Document Sharing Permissions

Overview of Document Sharing (ACLs)

Document sharing is controlled via the access control list feed. Access control lists are just basic lists that show who has access to a given resource. In the ACL feed, we have the following roles for a given document:

  • owner — the owner of the document. As an owner you have the ability to modify the ACL feed, delete the document, etc.
  • writer — a collaborator.
  • reader — a viewer (equivalent to read-only access).

Note: Please note that the accepted values for each role are case-sensitive. Also note that you cannot change the 'owner' role for a document.

Retrieving the ACL feed for a Document

The ACL feed can be retrieved by acessing the <gd:feedLink> element. Please note that you must use the full projection to receive 'gd' specific extension elements in your DocumentsList feed. The 'rel' attribute must correspond to http://schemas.google.com/acl/2007#accessControlList

GET /feeds/acl/private/full/document%3A<your document id> HTTP/1.1
Host: docs.google.com
Authorization: <your authorization header here>

This feed will contain an <entry> element for each ACL entry that exists for the given document.

The XML snippet below shows the ACL feed for the example document. Note that the feed contains three ACL entries. The <id> element of each ACL entry ends with the email address of the specific user that the ACL entry corresponds to:

  • document.owner%40example.com — the ACL entry for the document's owner
  • a.writer%40example.com — the ACL entry for a collaborator
  • a.reader%40example.com — the ACL entry for a reader
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
  xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <id>http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/id>
  <updated>2008-09-03T22:03:04.733Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
  <title type='text'>Document Permissions</title>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' 
  href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>' />
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
  href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>' />
  <link rel='self' type='application/atom+xml'
  href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>' />
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>

  <entry>
    <id>http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Adocument.owner%40example.com</id>
    <updated>2008-09-03T22:03:04.756Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - document.owner@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Adocument.owner%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Adocument.owner%40example.com' />
    <gAcl:role value='owner' />
    <gAcl:scope type='user' value='document.owner@example.com' />
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.writer%40example.com</id>
    <updated>2008-09-03T22:03:04.762Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - a.writer@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.writer%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.writer%40example.com' />
    <gAcl:role value='writer' /> 
    <gAcl:scope type='user' value='a.writer@example.com' />
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.reader%40example.com</id>
    <updated>2008-09-03T22:03:04.763Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - a.reader@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.reader%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Aa.reader%40example.com' />
    <gAcl:role value='reader'/> 
    <gAcl:scope type='user' value='a.reader@example.com' />
  </entry>
</feed>

Modifying the ACL feed for a Document

The ACL feed accepts GET, POST and PUT requests. To insert a new role into the ACL feed, simply issue a POST request. Please note that you need to be the document's owner to modify the ACL feed. The example belows how to insert a new collaborator to the document:

POST /feeds/acl/private/full/document%3A<your document id> HTTP/1.1
Host: docs.google.com
Authorization: <your authorization header here>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <category scheme='http://schemas.google.com/g/2005#kind'     
    term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='a_new_writer@example.com'/>
</entry>

The new entry is returned on a successful insertion:

<entry>
  <id>http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com</id>
  <updated>2008-09-11T03:10:00.913Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'    
    term='http://schemas.google.com/acl/2007#accessRule'/>
  <title type='text'>Document Permission - new_writer@gmail.com</title>
  <link rel='self' type='application/atom+xml' href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com'/>
  <link rel='edit' type='application/atom+xml' href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='new_writer@gmail.com'/>
</entry>

To update the entry, we will need to issue an HTTP PUT request to the entry's edit link, which is simply a <link> element, whose 'rel' attribute is set to 'edit'. In our case it is:

<link rel='edit'
  type='application/atom+xml'   
  href='http://docs.google.com/feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com'/>

The snippet below changes the entry's role to that of a 'reader':

PUT /feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com HTTP/1.1
Host: docs.google.com
Authorization: <your authorization header here>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='reader'/>
  <gAcl:scope type='user' value='new_writer@gmail.com'/>
</entry>

To remove permissions for this user, issue a DELETE request to the same edit link that was used for the PUT request:

DELETE /feeds/acl/private/full/document%3A<your document id>/user%3Anew_writer%40gmail.com HTTP/1.1
Host: docs.google.com
Authorization: <your authorization header here>

HTTP/1.1 200 OK

Back to top