Batch Resource

Use this resource to minimize the number of round-trips between the client and the server. For example, in a mobile app, when a user taps the button to like a feed item, the response body includes information about the like, but it doesn’t include the total number of likes on the feed item. To like the feed item, POST a request to /chatter/feed-items/feedItemId/likes. To get the like total, GET the feed item information from /chatter/feed-items/feedItemId.

Add both requests to a Batch Input request body and send them both in a single POST request to /connect/batch:

1{
2   "batchRequests" : [
3    {
4       "method" : "Post",
5       "url" : "/v30.0/chatter/feed-items/feedItemId/likes"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v30.0/chatter/feed-items/feedItemId"
10    }
11   ],
12   "haltOnError" : "false"
13}

The requests in a batch are called subrequests. All subrequests are executed in the context of the same user. Subrequests are independent and information can’t be passed between them. Subrequests execute serially in their order in the request body. When a subrequest executes successfully, it commits its data. Commits are reflected in the output of later subrequests (as in the previous example which liked a feed-item then got the total number of likes). If a subrequest fails, commits made by previous subrequests are not rolled back.

To upload a binary file with a subrequest, send it as a body part in a multipart/form-data request and include information about the file in the richInput object in the request body. See Uploading Binary Files.

Resource

1/connect/batch

Available since version

28.0

HTTP methods

POST

Request body

Batch Input

Root XML Tag

<batch>

JSON

1{
2   "batchRequests" : [
3    {
4       "method" : "Get",
5       "url" : "/v28.0/chatter/feeds/news/me"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v28.0/chatter/feeds/user-profile/me"
10    }
11   ]
12}

Properties

Name	Type	Description	Available Version
batchRequests	Batch Request Input[]	Collection of Batch Request Input request bodies containing the subrequest URLs to execute.	28.0
haltOnError	Boolean	The default value is false. If the value is false and a subrequest in the batch does not complete, Salesforce attempts to execute subsequent subrequests in the batch. If the value is true and a subrequest in the batch does not complete due to an HTTP response in the 400 or 500 range, Salesforce halts execution. It does not attempt to execute subsequent subrequests in the batch, and it returns an HTTP 412 status code and a BATCH_PROCESSING_HALTED error message for each subsequent subrequest indicating that a previous request was unsuccessful. The top-level request to /connect/batch returns HTTP 200 and the hasErrors property in the response is set to true.	28.0

Batch Request Input

Root XML Tag

<request>

JSON

1{
2   "method" : "Get",
3   "url" : "/v28.0/chatter/feeds/news/me"
4}

Properties

Name	Type	Description	Available Version
binaryPartName	String	The name of the binary part in the multipart request. When there are multiple binary parts uploaded in one batch request, this value is used to map a request to its binary part. To prevent name collisions, use a unique value for each binaryPartName property in a batch request. This property is optional. If this value exists, a binaryPartNameAlias value must also exist.	28.0
binaryPartNameAlias	String	The name parameter in the Content-Disposition header of the binary body part. Different resources expect different values. See Uploading Binary Files. This property is optional. If this value exists, a binaryPartName value must also exist.	28.0
method	String	The HTTP method of the request. One of these values: Delete Get Head Patch Post Put	28.0
richInput		The input body for the request. The type depends on the request specified in the url property. This property is optional.	28.0
url	String	The Chatter API resource to request. This value is called a subrequest. The subrequest URL can start with: /services/data/version, for example, /services/data/v30.0​​​/chatter/users/me. /version, for example, /v30.0/chatter​​​/users/me. The version number must be less than or equal to the version of the request given to the /connect/batch request URL. Additional information about subrequests: The URL can include any query string parameters that the subrequest supports. The query string must be URL-encoded. You can use parameters to filter response bodies. You cannot apply headers at the subrequest level.	28.0

Request parameters

None.

Response

Batch Results

Example

This simple example is a POST request made to https://instance_name/services/data/v30.0/connect/batch that includes the following request body containing two subrequests:

1swfobject.registerObject("clippy.codeblock-4", "9");{
2   "batchRequests" : [
3    {
4       "method" : "Get",
5       "url" : "/v30.0/chatter/feeds/user-profile/me"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v30.0/chatter/feeds/news/me"
10    }
11   ]
12}

The Batch Results response body includes a Batch Result Item response body for each subrequest:

1swfobject.registerObject("clippy.codeblock-5", "9");{
2   "hasErrors": false,
3   "results": [
4      {
5         "result": {
6            "feedItemsUrl": "/services/data/v30.0/chatter/feeds
7/user-profile/005D0000001LL8OIAW/feed-items",
8            "isModifiedUrl": null
9         },
10         "statusCode": 200
11      },
12      {
13         "result": {
14            "feedItemsUrl": "/services/data/v30.0/chatter/feeds
15/news/005D0000001LL8OIAW/feed-items",
16            "isModifiedUrl": null
17         },
18         "statusCode": 200
19      }
20   ]
21}

Example: haltOnError is true

This example is the same as the previous example but it includes an error in the first subrequest and haltOnError is set to true. Note that the first subrequest contains a typo.

1swfobject.registerObject("clippy.codeblock-6", "9");{
2   "batchRequests" : [
3    {
4       "method" : "Get",
5       "url" : "/v30.0/chatter/feeds/user-profile/men"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v30.0/chatter/feeds/news/me"
10    }
11   ],
12   "haltOnError" : "true"
13}

The Batch Results response body includes a Batch Result Item response body for each subrequest. The top-level request to /connect/batch returns an HTTP 200, but the first subrequest returns an HTTP 404 because the resource can’t be found. Because haltOnError is true, the next subrequest returns an HTTP 412. Also note that hasErrors is true.

1swfobject.registerObject("clippy.codeblock-7", "9");{
2   "hasErrors": true,
3   "results": [
4      {
5         "result": [{
6            "errorCode": "NOT_FOUND",
7            "message": "The requested resource does not exist"
8         }],
9         "statusCode": 404
10      },
11      {
12         "result": [{
13            "errorCode": "BATCH_PROCESSING_HALTED",
14            "message": "Batch processing halted per request"
15         }],
16         "statusCode": 412
17      }
18   ]
19}

Example: Uploading Binary Files

This example is a batch request that contains two subrequests. Each subrequest creates a feed item and uploads a binary file attachment to it.

The POST request is made to https://instance_name/services/data/v30.0/connect/batch.

This is the multipart/form-data request body:

1swfobject.registerObject("clippy.codeblock-8", "9");--123123
2Content-Disposition: form-data; name="json"
3Content-Type: application/json
4
5{
6    "haltOnError": "true",
7    "batchRequests": [
8        {
9            "method": "Post",
10            "url": "/v30.0/chatter/feeds/news/me/feed-items",
11            "binaryPartName": "binaryPart0",
12            "binaryPartNameAlias": "feedItemFileUpload",
13            "richInput": {
14                "attachment": {
15                    "attachmentType": "NewFile",
16                    "description": "description0",
17                    "title": "contentFile0"
18                },
19                "body": {
20                    "messageSegments": [
21                        {
22                            "type": "Text",
23                            "text": "textValue0"
24                        }
25                    ]
26                }
27            }
28        },
29        {
30            "method": "Post",
31            "url": "/v30.0/chatter/feeds/news/me/feed-items",
32            "binaryPartName": "binaryPart1",
33            "binaryPartNameAlias": "feedItemFileUpload",
34            "richInput": {
35                "attachment": {
36                    "attachmentType": "NewFile",
37                    "description": "description1",
38                    "title": "contentFile1"
39                },
40                "body": {
41                    "messageSegments": [
42                        {
43                            "type": "Text",
44                            "text": "textValue1"
45                        }
46                    ]
47                }
48            }
49        }
50    ]
51}
52--123123
53Content-Disposition: form-data; name="binaryPart0"; filename="file1.txt"
54Content-Type: application/octet-stream; charset=ISO-8859-1
55Content-Transfer-Encoding: binary
56
57This is content of file 1
58--123123
59Content-Disposition: form-data; name="binaryPart1"; filename="file2.txt"
60Content-Type: application/octet-stream; charset=ISO-8859-1
61Content-Transfer-Encoding: binary
62
63This is the content of file 2
64--123123--
65