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 and response 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.