Kaizen #61 - Composite API

Kaizen #61 - Composite API

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!
The Composite API does it all!

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.
  1. Sub Requests are executed under the same transaction (rollback can be performed)
  2. 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",
                        "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}"
                    }
                ]
            }
        }
    ]
}

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":[
                    {
                        "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"
                    }
                ]
            }
        }
    ]
}

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

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!



            Zoho Marketing Automation

                    Zoho Pagesense Resources

                      Zoho SalesIQ Resources



                            Zoho TeamInbox Resources

                              Zoho DataPrep Resources



                                Zoho CRM Plus Resources

                                  Zoho Books Resources


                                    Zoho Subscriptions Resources

                                      Zoho Desk Resources

                                        Zoho Projects Resources


                                          Zoho Sprints Resources


                                            Qntrl Resources


                                              Zoho Creator Resources


                                                Zoho WorkDrive Resources





                                                    Zoho Campaigns Resources

                                                      Zoho CRM Resources

                                                            Design. Discuss. Deliver.

                                                            Create visually engaging stories with Zoho Show.

                                                            Get Started Now