Reducing the number of calls

Good integration design typically involves writing integration points so that the number of calls between services is as small as possible. Cloud API includes multiple features that let caller applications execute multiple requests in a single call. This topic provides an overview of these features.

Features that execute multiple requests at once

Cloud API has several features that let caller applications execute multiple requests in a single call.

Composite requests are requests that consist of multiple sibling subrequests, with no parent request. Each subrequest is executed transactionally in the order it appears. If a given subrequest that attempts to commit data fails, the entire composite request fails. Information can be passed from one subrequest to another.

For details about composite requests, see Composite requests.

Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:

  • A single parent request that creates or modifies a resource
  • One or more child requests that create or modify resources related to the parent resource

If either the parent request or any child request fails, the entire request fails.

For details about request inclusion, see Request inclusion.

Batch requests are requests which consist of multiple sibling subrequests, with no parent request. Each subrequest is executed non-transactionally in the order it appears. If a given subrequest fails, other subrequests in the batch might still be attempted. Also, there is no mechanism for passing information from one subrequest to another. Each subrequest is essentially independent from the others.

For details about batch requests, see Batch requests.

The Graph API provides endpoints that allow you to create all the elements of an account or a submission, including all child elements, with a single command. The endpoints return complete account and submission graphs.

For more on the Graph API, see Streamlined account and submission creation.

Comparing features that execute multiple requests

Composite requests Request inclusion Batch requests

Architecture of the call

 Sibling subrequests (with no parent request) A parent request with one or more child requests Sibling subrequests (with no parent request)
The endpoint to call The Composite API's /composite endpoint The endpoint that creates or modifies the parent object (though not all endpoints support request inclusion) The relevant API's /batch endpoint
Behavior when one subrequest that attempts to commit data fails The entire request fails The entire request fails Other subrequests may still be attempted
Passing information between subrequests Through the use of variables Through the use of refids Not supported
Allows GET subrequests? Yes No Yes
Allows DELETE subrequests? Yes No Yes
Allows business action POST subrequests (such as /assign)? Yes No Yes
Allows the creation or modification of two unrelated objects? Yes No Yes

Determining which feature to use

There is no simple algorithm for determining the appropriate feature to use. In some situations, it may be possible to use multiple features, but it's easier to write the code using one particular feature.

At a high level, composite requests are typically the most robust option. If there is a choice of which feature to use, it may be best or easiest to use composite requests.

The following guidelines may also help you determine the best feature to use:

  • Use composite requests or request inclusion if:
    • All subrequests must succeed or fail as a unit.
    • Information must be passed from one subrequest to another.
    • The subrequests must use endpoints from different APIs.
  • Use composite requests or batch requests if at least some of the subrequests are GETs, DELETEs, or business action POSTs.
  • Use a composite request with the Graph API endpoints to create a complete account and submission and then quote and bind the submission.