Documents List API

  Google Docs supports sharing collections and their contents with others. This allows multiple Google Docs resources to be shared at once, and for additional resources added to the collection later to be automatically shared. Class.io, an EDU application on the Google Apps Marketplace, uses this technique. When a professor creates a new course, the application automatically creates a Google Docs collection for that course and shares it with all the students. This gives the students and professor a single place to go in Google Docs to access and manage all of their course files. A collection is a Google Docs resource that contains other resources, typically behaving like a folder on a file system. A collection resource is created by making an HTTP POST to the feed link with the category element’s term set to http://schemas.google.com/docs/2007#folder, for example:

  Example Collection

To achieve the same thing using the Python client library, use the following code:

from gdata.docs.data import Resource

collection = Resource('folder')
collection.title.text = 'Example Collection'

# client is an Authorized client
collection = client.create_resource(entry)

The new collection returned has a content element indicating the URL to use to add new resources to the collection. Resources are added by making HTTP POST requests to this URL.

This process is simplified in the client libraries. For example, in the Python client library, resources can be added to the new collection by passing the collection into the create_resource method for creating resources, or the move_resource method for moving an existing resource into the collection, like so:

# Create a new resource of document type in the collection
new_resource = Resource(type='document', title='New Document')
       client.create_resource(new_resource, collection=collection)

# Move an existing resource
client.move_resource(existing_resource, collection=collection)

Once resources have been added to the collection, the collection can be shared using ACL entries. For example, to add the user user@example.com as a writer to the collection and every resource in the collection, the client creates and adds the ACL entry like so:

from gdata.acl.data import AclScope, AclRole
from gdata.docs.data import AclEntry

acl = AclEntry(
    scope = AclScope(value='user@example.com', type='user'),
    role = AclRole(value='writer')
)

client.add_acl_entry(collection, acl)

The collection and its contents are now shared, and this can be verified in the Google Docs user interface:

Note: if the application is adding more than one ACL entry, it is recommended to use batching to combine multiple ACL entries into a single request. For more information on this best practice, see the latest blog post on the topic. The examples shown here are using the raw protocol or the Python client library. The Java client library also supports managing and sharing collections. For more information on how to use collections, see the Google Documents List API documentation. You can also find assistance in the Google Documents List API forum.