Hello everyone!
Have you ever wanted to make different API calls in a single request?
Save up on some API credits while still fulfilling your business case?
Reduce the round-trip time of a request?
We have got you!
What is a Composite API?
The Composite API allows you to combine up to five API requests in a single API call. You can also choose to execute all the APIs in a single database transaction, if required.
Before we look at this API in detail, let us get to know a few terms for better understanding.
- Sub-requests - the individual API requests you use in a composite request.
- Single database transaction - execution is considered complete only after all the sub-requests are executed.
- Round-trip time(RTT) - the time taken for the request to reach the server from the client and render a response in the client.
- Rollback - when one of the sub-requests fails, the previous sub-requests that were executed will be reverted, and the composite API will be rolled back.
- Concurrent execution - processing all the sub-requests at the same time, i.e, in parallel.
- Index of the sub-requests - represents the order of execution. The execution begins at the 0th index.
How does the composite API reduce the round-trip time(RTT)?
Consider that you want to fetch the module metadata of leads, insert a contact, and fetch a quote. When you combine these calls in a composite request, the RTT is much lesser than the three individual requests from and to the client.
Concurrent and parallel execution
You can execute the sub-requests sequentially or in parallel, depending on your business needs.
The Boolean keys rollback_on_fail and concurrent_execution decide the execution flow of the composite API.
- concurrent_execution - Represents whether you want to execute all the sub-requests in parallel.
- rollback_on_fail - Represents whether you want to rollback the entire composite request when one sub-request fails.
Note that these two keys cannot have the value "true" at the same time. That is, when the concurrent execution is true, a rollback cannot happen.
Let us discuss the two scenarios based on the values of these keys.
- Sub Requests are executed under the same transaction (rollback can be performed)
- Sub Requests are not executed under the same transaction
1. Sub-requests are executed under the same transaction (rollback can be performed)
- When to use?
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. - concurrent_execution - false
- rollback_on_fail - true
Here is the JSON for the composite request:
{ "rollback_on_fail": true, "concurrent_execution" : false, "__composite_requests": [ { "sub_request_id":"1", "method":"POST", "uri":"/crm/v3/Contacts/upsert", "headers":{}, "body": { "data":[ { "Last_Name":"composite", } ] } }, { "sub_request_id":"2", "method":"POST", "uri":"/crm/v3/Accounts/upsert", "body":{ "data":[ { "Account_Name":"C1", } ] } }, { "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}" } ] } } ] } |
2. Sub Requests are not executed under the same transaction
a. concurrent execution is false
- When to use?
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 concurrent execution. - concurrent_execution - false
- rollback_on_fail - false
{ "concurrent_execution" : false, "__composite_requests": [ { "sub_request_id":"1", "method":"PUT", "uri":"/crm/v3/Vendors/111111000000050313", "headers":{}, "body": { "data":[ { "Vendor_Name":"V1" } ] } }, { "sub_request_id":"2", "method":"POST", "uri":"/crm/v3/Contacts", "body":{ "data":[ { "Vendor_Name":"111111000000050313", "Last_Name":"composite", } ] } } ] } |
b. concurrent execution is true
Case 1: With independent sub-requests
- When to use?
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,. - concurrent_execution - true
- rollback_on_fail - false
Case 2: With dependent and independent sub-requests
- When to use?
When you have dependent and independent requests, and you want to execute independent requests in parallel to reduce execution time. For example, you want to create a lead(sub-request 1), create a contact referencing an account(sub-request 2) which will be created in another sub-request, and create an account(sub-request 3). Here, sub-requests 1 and 3 will be executed in parallel, and sub-request 2 will be executed after receiving the response from 3. - concurrent_execution - true
- rollback_on_fail - false
Here is the sample input.
{ "concurrent_execution" : true, "__composite_requests": [ { "sub_request_id":"1", "method":"POST", "uri":"/crm/v3/Leads", "headers":{}, "body": { "data":[ { "Last_Name":"composite", } ] } }, { "sub_request_id":"2", "method":"POST", "uri":"/crm/v3/Contacts", "body":{ "data":[ { "Account_Name":"@{1:$.data[0].details.id}", "Last_Name":"composite", } ] } }, { "sub_request_id":"3", "method":"POST", "uri":"/crm/v3/Accounts", "body":{ "data":[ { "Account_Name":"A1" } ] } } ] } |
Points to remember
- rollback_on_fail and concurrent_execution keys cannot hold the value "true" at the same time.
- You can only use a set of allowed APIs in the composite request. Refer to the Allowed APIs section on the help page.
- When rollback_on_fail is true, the automation actions are executed only when all the sub-requests are served and a rollback is not performed. If one or more sub-requests fail and a rollback happens, the automation actions are not triggered.
- Each composite API consumes one API credit, five concurrency credits, irrespective of the number of sub-requests.
How are responses and errors handled in the composite API
- A composite API renders a success response when all the sub-requests are executed irrespective of their success or failure.
- Every sub-request will have its corresponding error or success response, irrespective of the flow(concurrent or sequential).
- You can get the details of the erroneous sub-request from the index in the response.
We hope you found this post useful. Let us know your thoughts in the comments.
Cheers!