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!


    Access your files securely from anywhere

        Zoho Developer Community

            Bootcamp
            Community
            Pricing
            Webinars
            What's New
            Integrations
            Contact Support
            Contact Sales

              Zoho Survey Resources
                Features
                Survey Templates
                Integrations
                Community
                iOS Mobile Surveys
                Pricing
                Android Mobile Surveys
                Insurvey Blogs
                Insight Blogs
                Tips & Tricks





                              Latest Feature Updates


                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day




                                      Zoho Marketing Automation
                                        Zoho SalesIQ Resources


                                              Manage your brands on social media
                                              Access Zoho Social

                                                Zoho Pagesense Resources


                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now