Stay organized with collections
Save and categorize content based on your preferences.
There are several principles you should follow when using the Google Docs API.
These include:
Edit backwards for efficiency
Plan for collaboration
Ensure state consistency using the
WriteControl
field
Take tabs into account
The following sections explain these principles.
Edit backwards for efficiency
Within a single call to the
documents.batchUpdate
method, order your requests in
descending order of index location. This eliminates the need to compute the
index changes due to insertions and deletions.
Plan for collaboration
Expect the document state to change. Between one method call and another, other
collaborators might update the document, 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. However,
as an API client your app must manage this. Even if you don't anticipate
collaboration on the document, it's important to program defensively and make
sure the document state remains consistent. For one way to ensure consistency,
review the WriteControl section.
Establish state consistency with WriteControl
When you read and then update a document, you can control the behavior of how
competing changes are handled using the
WriteControl
field in the documents.batchUpdate method. WriteControl provides authority
over how write requests are executed.
Here's how you use it:
Get the document using the
documents.get
method and save the
revisionId
from the returned documents resource.
Compose your update requests.
Include an optional WriteControl
object with one of two options:
The requiredRevisionId field is set to the revisionId of the
document the write request is applied to. If the document was modified
since the API read request, the write request isn't processed and it
returns an error.
The targetRevisionId field is set to the revisionId of the document
the write request is applied to. If the document was modified since the
API read request, the write request changes are applied against the
collaborator changes. The result of the write request incorporates both
the write request changes and the collaborator changes into a new
revision of the document. The Docs server is responsible
for merging the content.
For an example of how to construct a batch request using WriteControl, see
this batch request example.
Take tabs into account
A single document can contain multiple tabs,
which require specific handling in your API requests.
Here's what to remember:
Set the includeTabsContent parameter to true in the
documents.get
method to retrieve the content from all tabs in a document. By default, not
all tab contents are returned.
Specify the ID(s) of the tab(s) to apply each Request
to in the
documents.batchUpdate
method. Each
Request
includes a way to specify the tabs to apply the update to. By default, if a
tab is not specified, the
Request
will in most cases be applied to the first tab in the document. Refer to the
Requests
documentation for specifics.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Best practices for best results\n\nThere are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n-----------------------------\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n----------------------\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n---------------------------------------------\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n----------------------\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n--------------\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]