Best practices for best results

There are a number of principles that you should follow when using the Google Docs API. These include:

  • Edit backwards for efficiency
  • Plan for collaboration
  • Use WriteControl to ensure state consistency

The following sections explain these principles.

Edit backwards for efficiency

Within a single call to the BatchUpdate method, order your requests in descending order of the index location. This eliminates the need to calculate the index changes due to insertions and deletions.

Plan for collaboration

Expect the document state to change. Between one method call and another, the document might have been updated by other collaborators, as shown in the following diagram:

This can lead to errors if your indexes are wrong. With multiple users editing a document using the UI, Google Docs takes care of this transparently, but as an API client your app must manage this. Even if you don't anticipate collaboration on the document, it is important to program defensively and make sure the document state remains consistent. See Use WriteControl for one way to ensure consistency.

Use WriteControl

When you read and then update a document, you can ensure that the document has not been updated by using the WriteControl field in the BatchUpdate method. This lets you make edits to the doc only if the version has not changed. Here's how you use it:

  1. Get the document and save the revisionId string that is included in it.
  2. Compose your update requests.
  3. Include a WriteControl object with the requiredRevisionId set to the string you saved.
  4. When you call BatchUpdate, it will return an error and update nothing if the document revision has changed.