Salesforce Composite API: Composite, Graph, Batch, Tree and Collections

Hey friends,

The Salesforce Composite API is a family of five REST resources that run several operations in one request: composite, composite graph, composite batch, sObject tree and sObject collections. They save round trips, and most of them count as a single API call. The differences that matter are how many subrequests each takes, whether one can use another's output and what happens to the rest when one fails.

Composite is the synchronous option in Salesforce API types, and it's what Salesforce points to for fewer than about 2,000 records, while Bulk API 2.0 takes the bigger loads. It comes up in the Design section of the Salesforce Certified Platform Integration Architect exam, so I've kept every limit tied to a Salesforce page.

What are the five composite resources?

Salesforce's API developer blog post compares them. The record counts below come from that post:

Everything above counts as one call toward your API limits except composite batch, where each subrequest counts.

How does the Composite resource work?

You POST a compositeRequest to /services/data/vXX.X/composite. Each subrequest has a method, a URL, a body and a referenceId, and later subrequests can use an earlier one's result with @{referenceId.id}. This example from the Composite resource page creates an Account and a Contact under it:

1{
2  "compositeRequest" : [{
3    "method" : "POST",
4    "url" : "/services/data/v68.0/sobjects/Account",
5    "referenceId" : "refAccount",
6    "body" : { "Name" : "Sample Account" }
7  },{
8    "method" : "POST",
9    "url" : "/services/data/v68.0/sobjects/Contact",
10    "referenceId" : "refContact",
11    "body" : {
12      "LastName" : "Sample Contact",
13      "AccountId" : "@{refAccount.id}"
14    }
15  }]
16}

A request can hold up to 25 subrequests, and up to 5 of them can be sObject collections or queries. The subrequests all run in one call, and the response carries each one's status and body.

What does allOrNone do?

It decides what happens when a subrequest fails. Per the Composite request body page, you set it at the top of the request body:

• allOrNone: true: the entire composite request is rolled back, and the top-level request still returns HTTP 200 with a response for each subrequest.
• allOrNone: false: the remaining subrequests that don't depend on the failed one still run. Dependent subrequests don't.

It gets trickier when you nest an sObject collections call inside a composite request, because both can have their own flag. The allOrNone parameters page spells out the four cases:

The rule to remember: the outer composite flag, when true, overrides the collection's flag. The collection's own flag defaults to false.

If you learn best by testing yourself, the Platform Integration Architect Cert Lab has quick practice questions on composite and bulk API choices, with every option explained.

When do I need a composite graph?

When one call needs a more complicated set of related records, or you want several independent groups that can succeed or fail on their own. The composite graph page says regular composite requests are limited to 25 subrequests and graphs raise that to 500. Each graph is all or nothing, and one graph failing doesn't affect the others.

Every graph has a graphId. It has to be unique in the request, start with an alphanumeric character, be shorter than 40 characters and not contain a period. Graph nodes only support three kinds of URL: create on sobjects/sObject, row operations on sobjects/sObject/id and row operations by external ID. Here's a small graph:

1{
2  "graphs": [{
3    "graphId": "graph1",
4    "compositeRequest": [{
5      "body": { "name": "Cloudy Consulting" },
6      "method": "POST",
7      "referenceId": "reference_id_account_1",
8      "url": "/services/data/v68.0/sobjects/Account/"
9    }, {
10      "body": {
11        "FirstName": "Nellie",
12        "LastName": "Cashman",
13        "AccountId": "@{reference_id_account_1.id}"
14      },
15      "method": "POST",
16      "referenceId": "reference_id_contact_1",
17      "url": "/services/data/v68.0/sobjects/Contact/"
18    }]
19  }]
20}

What is composite batch for?

Independent work. The composite batch page says it runs up to 25 subrequests in order, all as the same user, and the subrequests can't pass information to each other. When one succeeds it commits, and a later failure doesn't undo it. Each subrequest counts against rate limits. Use it to update a record and read something unrelated in one trip. Use composite or a graph if the steps depend on each other.

What are sObject tree and sObject collections?

sObject tree creates nested parent and child records, like an Account with its Contacts, in one request. The sObject tree page lists the limits: 200 records in total across all trees, up to five record types, five levels deep. Records are created in the order you list them, and if one fails the entire request fails. Triggers fire separately for each group of records at the same level, for example all the second-level Contacts.

sObject collections run one action on many records, with the whole request counting as a single API call. The collections page says it's available in API version 42.0 and later. For writes, allOrNone is optional and defaults to false, and for creates you set the type on each record and leave the ID off. Updates need both the ID and the type.

How do I choose between them?

How does Composite API show up on the exam?

As a requirement with a hint in it. "Create an account and its contacts in one transaction" points to composite or sObject tree. "Roll everything back if anything fails" points to allOrNone. "Several related record sets, each independent" points to composite graph. "Fewer calls to stay under API limits" points to any of them over single REST calls. The study plan page has a practice question on it: see the practice questions.

I'll be honest about how I learned this stuff. I loved Focus on Force and used it through 17 Salesforce certifications. Reading the study guide first was slow for me; taking practice tests rapid-fire and studying every wrong answer was fast. So when I built Cert Lab, I built it around that: test yourself quickly, see why each option is right or wrong.

FAQ

What is the Composite API in Salesforce?

A set of REST resources that run multiple operations in one request: composite, composite graph, composite batch, sObject tree and sObject collections.

How many subrequests can a composite request have?

Up to 25, and only 5 of them can be queries or sObject collections. Composite graph raises the limit to 500 across up to 75 graphs.

Does Composite API count as one API call?

Yes for composite, graph, tree and collections. The exception is composite batch, where each subrequest counts toward your limits.

What does allOrNone do in a composite request?

When true, the whole request rolls back if any subrequest fails. When false, subrequests that don't depend on the failed one still run.

What is the difference between composite and composite batch?

Composite subrequests can use each other's results and can roll back together. Composite batch subrequests are independent and commit one by one.

Where should you go next?

• Salesforce Bulk API 2.0 for the large-volume side.
• Salesforce API types for the full comparison.
• Apex trigger best practices since triggers fire on every record you write.
• Platform Integration Architect study plan for the full exam.

Nick Frates, a senior Salesforce developer with 17 certifications, built the Platform Integration Architect Cert Lab at nickfrates.com: rapid-fire practice questions for every exam section, each answer explained.

Hope this helps!

Best,

Nick