Batch Requests
Stay organized with collections
Save and categorize content based on your preferences.
This document shows how to batch API calls together to reduce the number of HTTP connections
your client has to make.
This document is specifically about making a batch request by sending an
HTTP request. If, instead, you're using a Google client library to make a batch request, see the client library's documentation.
Overview
Each HTTP connection your client makes results in a certain amount of overhead. The Google Mirror API supports batching, to allow your client to put several API calls into a single HTTP request.
Examples of situations when you might want to use batching:
- You've just started using the API and you have a lot of data to upload.
- A user made changes to data while your application was offline (disconnected from the Internet), so your application needs to synchronize its local data with the server by sending a lot of updates and deletes.
In each case, instead of sending each call separately, you can group them together into a single HTTP request. All the inner requests must go to the same Google API.
You're limited to 1000 calls in a single batch request. If you must make more calls than that, use multiple batch requests.
Note: The batch system for the Google Mirror API uses the same syntax as the OData batch processing system, but the semantics differ.
Batch details
A batch request consists of multiple API calls combined into one HTTP request, which can be sent to the batchPath specified in the API discovery document. The default path is /batch/api_name/api_version. This section describes the batch syntax in detail; later, there's an example.
Note: A set of n requests batched together counts toward your usage limit as n requests, not as one request. The batch request is separated into a set of requests before processing.
A batch request is a single standard HTTP request containing multiple Google Mirror API calls, using the multipart/mixed content type. Within that main HTTP request, each of the parts contains a nested HTTP request.
Each part begins with its own Content-Type: application/http HTTP header. It can also have an optional Content-ID header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.
The body of each part is a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.
The HTTP headers for the outer batch request, except for the Content- headers such as Content-Type, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.
For example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.
When the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.
Response to a batch request
The server's response is a single standard HTTP response with a multipart/mixed content type; each part is the response to one of the requests in the batched request, in the same order as the requests.
Like the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a Content-Type header that marks the beginning of the part.
If a given part of the request had a Content-ID header, then the corresponding part of the response has a matching Content-ID header, with the original value preceded by the string response-, as shown in the following example.
Note: The server might perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.
Example
The following example shows the use of batching with the Google Mirror API.
Example batch request
POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==--
Example batch response
This is the response to the example request in the previous section.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "0987654321",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "5432109876",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-08-06 UTC.
[[["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 2024-08-06 UTC."],[[["\u003cp\u003eBatching allows you to combine multiple Google Mirror API calls into a single HTTP request to reduce overhead.\u003c/p\u003e\n"],["\u003cp\u003eEach batched call is counted towards your usage limit and the server may execute them out of order.\u003c/p\u003e\n"],["\u003cp\u003eA batch request uses \u003ccode\u003emultipart/mixed\u003c/code\u003e content type and nests individual API calls as parts within the main request.\u003c/p\u003e\n"],["\u003cp\u003eThe server's response to a batch request mirrors its structure, providing individual responses for each call in the same order.\u003c/p\u003e\n"],["\u003cp\u003eUse batching for scenarios like initial data uploads or synchronizing offline changes, but limit each request to 1000 calls.\u003c/p\u003e\n"]]],[],null,["This document shows how to batch API calls together to reduce the number of HTTP connections\nyour client has to make.\n\nThis document is specifically about making a batch request by sending an\nHTTP request. If, instead, you're using a Google client library to make a batch request, see the [client library's documentation](https://developers.google.com/api-client-library/).\n\nOverview\n\nEach HTTP connection your client makes results in a certain amount of overhead. The Google Mirror API supports batching, to allow your client to put several API calls into a single HTTP request.\n\nExamples of situations when you might want to use batching:\n\n- You've just started using the API and you have a lot of data to upload.\n- A user made changes to data while your application was offline (disconnected from the Internet), so your application needs to synchronize its local data with the server by sending a lot of updates and deletes.\n\nIn each case, instead of sending each call separately, you can group them together into a single HTTP request. All the inner requests must go to the same Google API.\n\nYou're limited to 1000 calls in a single batch request. If you must make more calls than that, use multiple batch requests.\n\n**Note** : The batch system for the Google Mirror API uses the same syntax as the [OData batch processing](http://www.odata.org/documentation/odata-version-3-0/batch-processing/) system, but the semantics differ.\n\n\nBatch details\n\nA batch request consists of multiple API calls combined into one HTTP request, which can be sent to the `batchPath` specified in the [API discovery document](https://developers.google.com/discovery/v1/reference/apis). The default path is `/batch/`\u003cvar translate=\"no\"\u003eapi_name\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eapi_version\u003c/var\u003e. This section describes the batch syntax in detail; later, there's an [example](#example).\n\n**Note** : A set of \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests batched together counts toward your usage limit as \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests, not as one request. The batch request is separated into a set of requests before processing.\n\nFormat of a batch request\n\nA batch request is a single standard HTTP request containing multiple Google Mirror API calls, using the `multipart/mixed` content type. Within that main HTTP request, each of the parts contains a nested HTTP request.\n\nEach part begins with its own `Content-Type: application/http` HTTP header. It can also have an optional `Content-ID` header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.\n\nThe body of each part is a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.\n\nThe HTTP headers for the outer batch request, except for the `Content-` headers such as `Content-Type`, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.\n\nFor example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.\n\nWhen the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.\n\nResponse to a batch request\n\nThe server's response is a single standard HTTP response with a `multipart/mixed` content type; each part is the response to one of the requests in the batched request, in the same order as the requests.\n\nLike the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a `Content-Type` header that marks the beginning of the part.\n\nIf a given part of the request had a `Content-ID` header, then the corresponding part of the response has a matching `Content-ID` header, with the original value preceded by the string `response-`, as shown in the following example.\n\n**Note**: The server might perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.\n\nExample\n\nThe following example shows the use of batching with the Google Mirror API.\n\nExample batch request \n\n```\nPOST /batch HTTP/1.1\nContent-Length: content_length\ncontent-type: multipart/mixed; boundary=\"===============7330845974216740156==\"\naccept-encoding: gzip, deflate\n\n--===============7330845974216740156==\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: TIMELINE_INSERT_USER_1\n\nPOST /mirror/v1/timeline HTTP/1.1\nContent-Type: application/json\nauthorization: Bearer user_1_token\naccept: application/json\ncontent-length: 24\n\n{\"text\": \"Hello there!\"}\n--===============7330845974216740156==\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: TIMELINE_INSERT_USER_2\n\nPOST /mirror/v1/timeline HTTP/1.1\nContent-Type: application/json\nauthorization: Bearer user_2_token\naccept: application/json\ncontent-length: 24\n\n{\"text\": \"Hello there!\"}\n--===============7330845974216740156==\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: TIMELINE_INSERT_USER_3\n\nPOST /mirror/v1/timeline HTTP/1.1\nContent-Type: application/json\nauthorization: Bearer user_3_token\naccept: application/json\ncontent-length: 24\n\n{\"text\": \"Hello there!\"}\n--===============7330845974216740156==--\n```\n\nExample batch response\n\nThis is the response to the example request in the previous section. \n\n```\nHTTP/1.1 200 OK\nContent-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=\nDate: Tue, 22 Jan 2013 18:56:00 GMT\nExpires: Tue, 22 Jan 2013 18:56:00 GMT\nCache-Control: private, max-age=0\n\n--batch_pK7JBAk73-E=_AA5eFwv4m2Q=\nContent-Type: application/http\nContent-ID: response-TIMELINE_INSERT_USER_1\n\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 304\n\n{\n \"kind\": \"glass#timelineItem\",\n \"id\": \"1234567890\",\n \"selfLink\": \"https://www.googleapis.com/mirror/v1/timeline/1234567890\",\n \"created\": \"2012-09-25T23:28:43.192Z\",\n \"updated\": \"2012-09-25T23:28:43.192Z\",\n \"etag\": \"\\\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\\\"\",\n \"text\": \"Hello there!\"\n}\n--batch_pK7JBAk73-E=_AA5eFwv4m2Q=\nContent-Type: application/http\nContent-ID: response-TIMELINE_INSERT_USER_2\n\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 304\n\n{\n \"kind\": \"glass#timelineItem\",\n \"id\": \"0987654321\",\n \"selfLink\": \"https://www.googleapis.com/mirror/v1/timeline/0987654321\",\n \"created\": \"2012-09-25T23:28:43.192Z\",\n \"updated\": \"2012-09-25T23:28:43.192Z\",\n \"etag\": \"\\\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\\\"\",\n \"text\": \"Hello there!\"\n}\n--batch_pK7JBAk73-E=_AA5eFwv4m2Q=\nContent-Type: application/http\nContent-ID: response-TIMELINE_INSERT_USER_3\n\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 304\n\n{\n \"kind\": \"glass#timelineItem\",\n \"id\": \"5432109876\",\n \"selfLink\": \"https://www.googleapis.com/mirror/v1/timeline/5432109876\",\n \"created\": \"2012-09-25T23:28:43.192Z\",\n \"updated\": \"2012-09-25T23:28:43.192Z\",\n \"etag\": \"\\\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\\\"\",\n \"text\": \"Hello there!\"\n}\n--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--\n```"]]
