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}"
                        }
                    ]
                }
            }
        ]
    }