Requests and responses

You invoke the Google Docs API using an HTTP request, or by using a method invocation in a language-specific client library. These are broadly equivalent, but it's much simpler to use the client library.

The API returns an HTTP response, which generally includes the result of the request invocation. When using a client library to make requests, the responses are returned in a language-specific way.

Request methods

The Docs API supports the following request methods:

  • create—Creates a new, blank Google Docs document.
  • get—Returns a complete instance of the specified document. You can parse the returned JSON to extract the document content, formatting, and other features.
  • batchUpdate—Submits a list of editing requests to apply to the document, and returns a list of results.

You can invoke these methods using a client library method, or directly as an HTTP request, with the response returned as appropriate for the invocation style. For details of these requests and responses, see the API reference.

Batch update

The batchUpdate method works by taking one or more Request objects, each one specifying a single request to perform. There are many different kinds of requests. Here's a breakdown of the types of requests, grouped into different categories.

Working with text replaceAllText
insertText
Working with styles updateTextStyle
updateParagraphStyle
createParagraphBullets
deleteParagraphBullets
Working with ranges createNamedRange
deleteNamedRange
deleteContentRange
Working with images insertInlineImage

A popular pattern for making batch requests looks like this:

requests = []
requests.append(some request)
requests.append(another one)
requests.append(and another one)
.
.
.
body = ... & requests & ...

...batchUpdate(body)

The API validates each request within a batchUpdate call before applying them. If any request is not valid, then the entire batch is unsuccessful and the document is left unchanged.

Some requests return responses that contain details of how the request was applied. Other requests just return an empty reply. The order of replies matches that of the requests.

For example, suppose you call batchUpdate with 4 updates, and only the third one returns information. The response would have 2 empty replies, the reply to the third request, and another empty reply, in that order.