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.
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:
- Get the document and save the
revisionIdstring that is included in it.
- Compose your update requests.
- Include a WriteControl` object with the requiredRevisionId set to the string you saved.
- When you call BatchUpdate, it will return an error and update nothing if the document revision has changed.