REST API Developer Guide
j
No Results
Search Tips:
- Please consider misspellings
- Try different search keywords
Composite Request Body
Composite Collection Input
- Properties
-
Name Type Description Required or Optional allOrNone Boolean Specifies what to do when an error occurs while processing a subrequest. If the value is true, the entire composite request is rolled back. The top-level request returns HTTP 200 and includes responses for each subrequest.
If the value is false, the remaining subrequests that don’t depend on the failed subrequest are executed. Dependent subrequests aren’t executed.
In either case, the top-level request returns HTTP 200 and includes responses for each subrequest.
Optional collateSubrequests Boolean Controls whether the API collates unrelated subrequests to bulkify them (true) or not (false).
When subrequests are collated, the processing speed is faster, but the order of execution is not guaranteed (unless there is an explicit dependency between the subrequests).
If collation is disabled, then the subrequests are executed in the order in which they are received.
Subrequests that contain valid HTTP headers are not collated.
In API version 49.0 and later, the default value is true. In version 48.0, the default value is false.
Subrequests can be collated if they meet these conditions:- The HTTP methods are the same.
- The API versions of the resources are the same.
- The parents of the resources are /sobjects resources.
- No more than five sObjects resources are present across a grouping of subrequests.
Available in API version 48.0 and later. (In earlier versions, subrequests cannot be collated.)
Optional compositeRequest Composite Subrequest[] Collection of subrequests to execute. Required - JSON example
-
{ "allOrNone" : true, "collateSubrequests": true, "compositeRequest" : [{ Composite Subrequest },{ Composite Subrequest },{ Composite Subrequest }] }
Composite Subrequest
- Properties
-
Name Type Description Required or Optional body Varies The input body for the subrequest. The type depends on the request specified in the url property. The referenceable types are DateTime, String, Boolean, Byte, Character, Short, Integer, Long, Double, and Float.
Optional httpHeaders Map<String, String> Request headers and their values to include with the subrequest. You can include any header supported by the requested resource except for the following three headers. - Accept
- Authorization
- Content-Type
Optional method String The method to use with the requested resource. Possible values are POST, PUT, PATCH, GET, and DELETE (case-sensitive). For a list of valid methods, refer to the documentation for the requested resource. Required referenceId String Reference ID that maps to the subrequest’s response and can be used to reference the response in later subrequests. You can reference the referenceId in either the body or URL of a subrequest. Use this syntax to include a reference: @{referenceId.FieldName}. You can use two operators with the reference ID.
The . operator references a field on a JSON object in the response. For example, let’s say you retrieve an account record’s data in one subrequest and assign the reference ID Account1Data to the output. You can refer to the account’s name in later subrequests like this: @{Account1Data.Name}.
The [] operator indexes a JSON collection in the response. For example, let’s say you request basic account information with the sObject Basic Information resource in one subrequest and assign the reference ID AccountInfo to the output. Part of the response includes a collection of recently created accounts. You can refer to the ID of the first account in the recent items collection like this: @{AccountInfo.recentItems[0].Id}.
You can use each operator recursively as long as it makes sense in the context of the response. For example, to refer to the billing city component of an account’s compound address field: @{NewAccount.BillingAddress.city}.
referenceId is case-sensitive, so pay close attention to the case of the fields you’re referring to. See Usage.
Required url String The resource to request. - 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.
- The URL must start with /services/data/vXX.X/.
Required - JSON examples
-
Example 1
-
{ "method" : "GET", "url" : "/services/data/v63.0/sobjects/Account/describe", "httpHeaders" : { "If-Modified-Since" : "Tue, 31 May 2016 18:00:00 GMT" }, "referenceId" : "AccountInfo" } -
Example 2
-
{ "method" : "POST", "url" : "/services/data/v63.0/sobjects/Account", "referenceId" : "refAccount", "body" : { "Name" : "Sample Account" } } -
Example 3
-
{ "method" : "GET", "url" : "/services/data/v63.0/sobjects/Account/@{refAccount.id}", "referenceId" : "NewAccountFields" } -
Example 4
-
{ "method" : "PATCH", "url" : "/services/data/v63.0/sobjects/Account/ExternalAcctId__c/ID12345", "referenceID" : "NewAccount", "body" : { "Name" : "Acme" } } - Usage
- Because referenceId is case-sensitive, it’s important to note the case of the fields that you’re referring to. The same field can use different cases in different contexts. For example, when you create a record, the ID field appears as id in the response. But when you access a record’s data with the sObject Rows resource, the ID field appears as Id. In Example 3, the @{refAccount.id} reference is valid because refAccount refers to the response from a POST like that shown in Example 2. If you use Id instead (mixed case rather than all lowercase), as in @{refAccount.Id}, you get an error when sending the request because the reference ID uses the wrong case.