Salesforce Composite resources

In this session we are going to exploring Salesforce composite resources / composite API. Use REST API composite resources are helpful to improve application’s performance by minimizing the number of round-trips between the client and server.

What is Composite Resources

let us see what is composite resources. We have seen standard Salesforce rest apis which we use to create or update data in salesforce from an external system these API‘s we do one at a time. Composite resources is an enhanced form of rest api which executes a series of rest api requests in a single call. It helps you to do multiple operations like read create update and delete Salesforce data in single callout.

You can use output of one request as the input to a subsequent request response bodies and status of all these rest api requests are together returned in a single response body. All the series of rest apis are counted as a single call towards your API limits. This is executed in the context of the same user.

1. Series of REST API requests in a single call.
2. Multiple CRUD Operations
3. Output of one request as the input to a subsequent request.
4. Response bodies and status in a single response body.
5. Counts as a single call toward your API limits.
6. Executed in context of the same user. 

Composite Resources consists of

Composite request body

Here you are seeing an example of composite request body

{
   "allOrNone" : true,
   "collateSubrequests": true,
   "compositeRequest" : [
     { Composite Subrequest},
     { Composite Subrequest},
     { Composite Subrequest}
   ]
}

• You can pass “allOrNone” a boolean which specifies what to do when an error occurs while processing a sub request if the value is true the entire composite request.
• collateSubrequests : Controls whether the API collates unrelated subrequests to bulkify them (true) or not (false)
• compositeRequest : Collection of subrequests to execute

Composite request response

Here we are getting the salesforce id as the composite response. Id you can see a success as true means this
api request was a success and the location would specify the id with the http status as 201 and the reference id is also returned

{
   "compositeResponse" : [
      {  Composite Subrequest Result },
      {  Composite Subrequest Result },
      {  Composite Subrequest Result }
   ]
}

Why Composite Resources

Lets understand the advantage of composite API.

• Multiple REST API calls for single call
• Processing speed can be made faster by collating the subrequests.
• Improves the performance of the application
• No additional coding required at Salesforce. 
• Single call toward API limits.
• Synchronous responses.
• Multiple ways in composite resources work.
• Upsert upto five levels deep relationships.
• Flexible on upserting related or non related records.
• Can do a GET subrequest and the result can be input to next POST subrequest.
• Can handle more complicated and related objects and data. 

Type of Composite Resources

There are different composite resources available

1. Composite API
2. Batch
3. SObject Tree
4. SObject Collection
5. Grapths

Salesforce Composite API

let’s see composite api. Composite api is having the same features of composite resources. We saw earlier it can execute series of api requests in a single call. Output of one request can be given as input to a subsequent request response bodies. Http status of the request are returned in a single response body. It also count as a single api call
towards the api limits. Formats are json and xml. Check the Recording for a demo of composite using postman.

Sample Request and URL.

URL : /services/data/vXX.X/composite

Request Body sample.

{
"compositeRequest" : [
  {
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Account",
  "referenceId" : "refAccount",
  "body" : { "Name" : "APEX HOURS" }
  },
  {
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Contact",
  "referenceId" : "refContact",
  "body" : { 
    "LastName" : "AMIT CHAUDHARY",
    "AccountId" : "@{refAccount.id}"
    }
  }]
}

Salesforce Composite Batch

The next composite resource what we are going to see is composite batch. It can execute up to 25 sub requests in a single request. Each subrequest count against the rate limits. Sub requests are independent. You cannot pass information between them sub requests execute serially in their order. Formats are json and xml and the url will have api version composite followed by batch. If a batch request doesn’t complete within 10 minutes the batch timeouts.

1. Upto 25 subrequests in a single request.
2. Each subrequest counts against rate limits.
3. Subrequests are independent. 
4. Serial execution order

Sample URL /services/data/vXX.X/composite/batch

{
  "batchRequests" : [
    {
    "method" : "PATCH",
    "url" : "v52.0/sobjects/account/001D000000K0fXOIAZ",
    "richInput" : {"Name" : "ApexHours"}
    },
    {
    "method" : "GET",
    "url" : "v52.0/sobjects/account/001D000000K0fXOIAZ?fields=Name,Type"
    }
 ]
}

SObject Collection

This one also executes action on multiple records in one request. The request body is different from the composite. We can observe up to 200 requests get delete patch post are available and the url will handle sObjects at the end you can choose whether to roll back the entire request when an error occurs. The list can contain objects of different type including custom objects objects are created in the order they are listed.

• Executes actions on multiple records in one request. 
• One request can handle only one object.
• Upsert upto 200 records.
• The list can contain objects of different types, including custom objects.
• Objects are created in the order they’re listed. 

Sample URI POST /services/data/vXX.X/composite/sobjects

{
   "allOrNone" : false,
   "records" : [{
      "attributes" : {"type" : "Account"},
      "Name" : "example.com",
      "BillingCity" : "Alpharetta"
   }, 
   {
      "attributes" : {"type" : "Contact"},
      "LastName" : "Chaudhary",
      "FirstName" : "Amit"
   }]
}

Salesforce Composite Tree

Creates one or more sObject trees with root records of the specified type. An sObject tree is a collection of nested, parent-child records with a single root record.

• sObject trees with root records of the specified type.
• Insert upto a total of 200 records across all trees. 
• SObject trees up to five levels deep. 
• Support only insert. No upsert.

URL : /services/data/vXX.X/composite/tree/sObjectName

{
"records" :[{
    "attributes" : {"type" : "Account", "referenceId" : "ref1"},
    "name" : "ApexHours",
    "phone" : "1234567890",
    "website" : "www.apexhours.com",
    "numberOfEmployees" : "1",
    "industry" : "Education",
    "Contacts" : {
      "records" : [{
         "attributes" : {"type" : "Contact", "referenceId" : "ref2"},
         "lastname" : "Chaudhary",
         "title" : "amit",
         "email" : "[email protected]"
         },{         
         "attributes" : {"type" : "Contact", "referenceId" : "ref3"},
         "lastname" : "Pooja",
         "title" : "Chugh",
         "email" : "[email protected]"
         }]
      }
    },{
    "attributes" : {"type" : "Account", "referenceId" : "ref4"},
    "name" : "Amit Salesforce",
    "phone" : "1234567890",
    "website" : "www.salesforce2.com",
    "numberOfEmployees" : "100",
    "industry" : "Banking"
     }]
}

Composite Graphs

Next is my favorite composite resource which is the composite graph this was released in winter 21.

• Provide an enhanced way to perform composite requests
• Can assemble a more complicated and complete series of related objects and records. 
• allorNone is always true for graph
• Composite graphs can handle 500 records.

URL: /services/data/vXX.X/sobjects/sObject

Composite graphs each sub request is called as a node. There can be multiple nodes possible since composite graphs is more advanced and complicated one so we’ll see this one in detail in recording

Limits and Considerations

• Not all composite resources support create and update.
• Inbound API call limit applies
• Troubleshoot
• Reference ID not in response for batch and sObject collections
• Same reference id cannot be used in same transaction – Duplicate reference id issue
• Same external id record of same object cannot be used in same transaction.