Composite API - An Overview

The composite API allows you to combine up to five API calls in a single request consuming just one credit per composite call. This API reduces the round-trip time and allows you to execute the APIs in a single database transaction, if needed.
By single database transaction, we mean that your request can have multiple sub-requests (individual APIs), and the execution can happen in a sequence. You will get a response when all the sub-requests are executed successfully, or after the entire composite request is rolled-back(all changes reverted) owing to the failure of a single sub-request.

What is Round-trip time (RTT) and how does this API reduce it?
The time taken for a client request to reach the server and render a response back in the client is called the Round-trip time.
Since you club all the requests in a composite API, round-trip time is saved. Should one or more of the sub-requests fail, you can choose to rollback (revert all the changes) the entire transaction.

The keys "rollback_on_fail" and "parallel_execution"

• rollback_on_fail: This boolean key represents whether you want to rollback the composite request when one or more sub-requests fail.

• parallel_execution: This boolean key represents whether you want to process all the independent sub-requests in parallel.

Let us discuss the two scenarios in which this API is at its best.

1. Sub-requests are not executed under the same transactionParallel execution is false

   • Use this flow when there are sub-requests that are internally dependent through an automation action.
     For example, you have configured a workflow that is triggered when the vendor's name is Zylker. In sub-request 1, you update an existing vendor's name from Zoho to Zylker. In sub-request 2, you create a contact associating the recently-updated vendor using its ID. Both appear like independent requests, but have internal dependency through the workflow. That is, to trigger the workflow, you must execute sub-request 1 first, followed by the second. Hence, you cannot use parallel execution.

     {
         "parallel_execution" : false,
         "__composite_requests": [
             {
                 "sub_request_id":"1",
                 "method":"PUT",
                 "uri":"/crm/v3/Vendors/111111000000050313",
                 "headers":{},
                 "body":
                 {
                     "data":[
                         {
                             "Email":"v@gmail.com",
                             "Vendor_Name":"V1"
                         }
                     ]
                 }
             },
             {
                 "sub_request_id":"2",
                 "method":"POST",
                 "uri":"/crm/v3/Contacts",
                 "body":{
                     "data":[
                         {
                             "Vendor_Name":"111111000000050313",
                             "Last_Name":"composite",
                             "Email":"composite2@test.test"
                         }
                     ]
                 }
             }
         ]
     }
     

   • Parallel execution is true
     • Case 1: With independent sub-requests
       

       Use this flow when your sub-requests are independent of each other and you want to save time by executing them in parallel. For example, fetching the leads, fetching the metadata of another module etc,.

     • Case 2: With dependent and independent sub-requests
       

       Use this when your sub-requests are independent of each other and you want to save time by executing them in parallel. For example, fetching the leads, fetching the metadata of another module etc,.

     {
         "parallel_execution" : true,
         "__composite_requests": [
             {
                 "sub_request_id":"1",
                 "method":"POST",
                 "uri":"/crm/v3/Leads",
                 "headers":{},
                 "body":
                 {
                     "data":[
                         {
                             "Last_Name":"composite",
                             "Email":"composite@test.test"
                         }
                     ]
                 }
             },
             {
                 "sub_request_id":"2",
                 "method":"POST",
                 "uri":"/crm/v3/Contacts",
                 "body":{
                     "data":[
                         {
                             "Account_Name":"@{1:$.data[0].details.id}",
                             "Last_Name":"composite",
                             "Email":"composite2@test.test"
                         }
                     ]
                 }
             },
             {
                 "sub_request_id":"3",
                 "method":"POST",
                 "uri":"/crm/v3/Accounts",
                 "body":{
                     "data":[
                         {
                             "Account_Name":"A1"
                         }
                     ]
                 }
             }
         ]
     }
     

2. Sub Requests are executed under the same transaction (rollback_on_fail:true, parallel_exec:false)
   When there are dependent sub-requests and the execution of one depends on the response of another sub-request. Here, you must reference the sub-request whose data you want to use in another sub-request.
   For example, you want to upsert a record in the Contacts module(sub-request 1), upsert a record in the Accounts module(sub-request 2), and convert a lead while associating it to the previously upserted contact and account(sub-request 3). Sub-request 3 depends on the execution of sub-requests 1 and 2. This allows you to rollback the composite request when one of the sub-requests fails. That is, the contact and account will not be upserted.
   The input would look like the following.

   {
       "rollback_on_fail": true,
       "parallel_execution" : false,
       "__composite_requests": [
           {
               "sub_request_id":"1",
               "method":"POST",
               "uri":"/crm/v3/Contacts/upsert",
               "headers":{},
               "body":
               {
                   "data":[
                       {
                           "Last_Name":"composite",
                           "Email":"composite@test.test"
                       }
                   ]
               }
           },
           {
               "sub_request_id":"2",
               "method":"POST",
               "uri":"/crm/v3/Accounts/upsert",
               "body":{
                   "data":[
                       {
                           "Account_Name":"C1",
                           "Email":"composite2@test.test"
                       }
                   ]
               }
           },
           {
               "sub_request_id":"3",
               "method":"POST",
               "uri":"/crm/v3/Leads/111111000000095001/actions/convert",
               "body":{
                   "data":[
                       {
                           "Accounts":"@{2:$.data[0].details.id}",
                           "Contacts":"@{1:$.data[0].details.id}"
                       }
                   ]
               }
           }
       ]
   }