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.
- 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" } ] } } ] }
- Case 1: With independent sub-requests
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}" } ] } } ] }