Mulesoft - Salesforce Composite Request and Composite Graph Request API Calls
The Salesforce Composite API and Composite Graph API are both REST API resources designed to execute multiple operations in a single API call, reducing the number of round-trips and optimizing API usage. However, they differ significantly in their capabilities, limits, and use cases.
Salesforce Composite Request
The Composite API allows you to execute a series of REST API subrequests in a single call, with the output of one subrequest potentially used as input for subsequent subrequests. It’s designed for simpler, sequential operations.
Key Features
- Endpoint: POST /services/data/vXX.X/composite
- Subrequest Limit: Up to 25 subrequests in a single call.
- Supported Operations: Supports CRUD operations (Create, Read, Update, Delete), SOQL queries, and other REST API resources (e.g., sObject operations, query, queryAll).
- Execution: Subrequests are executed sequentially in the order specified in the request body.
- Dependency: Subrequests can reference the output of previous subrequests using referenceId (e.g., @{previousRequestId.field}).
- Transactionality:
- Controlled by the allOrNone parameter. If true, all subrequests are rolled back if any fail; if false, successful subrequests are committed even if others fail.
- Individual sObject Collection subrequests can also specify their own allOrNone behavior.
- Limitations:
- Maximum of 5 query operations (SOQL queries or QueryAll) within the 25 subrequests.
- Reference IDs must contain only letters, numbers, and underscores. In API v51.0 and earlier, illegal characters cause the subrequest to fail; in v52.0 and later, the entire request fails.
- References to null fields behave differently based on API version: in v51.0 and earlier, they cause the dependent subrequest to fail; in v52.0 and later, the request succeeds.
Create an Account and a related Contact in a single call
Pros
- Simplifies workflows by combining multiple REST API calls into one, reducing API limits usage
- Supports dependency between subrequests, allowing the output of one to feed into another.
- Suitable for small-to-medium-sized operations (e.g., creating a parent and child records).
Cons
- Limited to 25 subrequests, which can be restrictive for complex operations.
- Limited to 5 query operations, requiring workarounds like breaking into multiple composite requests.
- Sequential execution may impact performance for larger sets of subrequests.
Salesforce Composite Graph API
The Composite Graph API, introduced in Winter ’21, is an advanced extension of the Composite API, designed for more complex and larger-scale operations. It organizes subrequests into graphs, where each graph represents a group of related operations, and supports a significantly higher limit of subrequests.
Key Features
- Endpoint: POST /services/data/vXX.X/composite/graph
- Subrequest Limit: Up to 500 nodes (subrequests) across all graphs in a single call, with a maximum of 15 depths (levels of dependency between nodes).
- Supported Operations: Similar to Composite API, supports CRUD operations, SOQL queries, and other REST resources.
- Execution: Subrequests within a graph are executed sequentially, but multiple graphs in a single request can be processed in parallel, improving performance for complex operations.
- Dependency: Subrequests (nodes) within a graph can reference each other’s output using referenceId, similar to Composite API. Each graph is identified by a graphId.
- Transactionality:
- Each graph is transactional, meaning all subrequests in a graph are either all completed or all rolled back, ensuring data consistency without needing to check for partial success.
- The allOrNone parameter applies at the graph level, not the entire request, allowing independent transactional control for each graph
Example:
- Returns a graphs array, where each graph contains a graphResponse with a compositeResponse array (similar to Composite API) and an isSuccessful boolean indicating if the graph succeeded.
- Example:
{"graphs": [{"graphId": "1","graphResponse": {"compositeResponse": [{"body": { "id": "001...", "success": true, "errors": [] },"httpHeaders": { "Location": "/services/data/v61.0/sobjects/Account/001..." },"httpStatusCode": 201,"referenceId": "parentAccount"},{"body": { "id": "003...", "success": true, "errors": [] },"httpHeaders": { "Location": "/services/data/v61.0/sobjects/Contact/003..." },"httpStatusCode": 201,"referenceId": "childContact"}]},"isSuccessful": true},{"graphId": "2","graphResponse": {"compositeResponse": [{"body": { "id": "001...", "success": true, "errors": [] },"httpHeaders": { "Location": "/services/data/v61.0/sobjects/Account/001..." },"httpStatusCode": 201,"referenceId": "anotherAccount"}]},"isSuccessful": true}]}
- Supports up to 500 subrequests, making it suitable for large-scale, complex operations.
- Transactional graphs ensure data consistency within each graph, reducing the need to handle partial failures.
- Parallel processing of multiple graphs improves performance for independent operations.
- Ideal for scenarios involving complex relationships (e.g., creating multiple parent-child records across different objects).
Cons
- More complex to implement due to the graph structure and higher limit management.
- Still subject to Salesforce governor limits (e.g., API call limits, query limits).
- Not all operations are supported (e.g., limited to specific URLs like sObject operations).
Key
Differences between Composite Request and Composite Graph Request
|
Feature |
Composite
Request |
Composite
Graph Request |
|
Endpoint |
/composite |
/composite/graph |
|
Subrequest Limit |
25 subrequests |
500 nodes (subrequests) |
|
Query Limit |
Max 5 SOQL queries |
No specific query limit mentioned,
but subject to governor limits |
|
Execution |
Sequential |
Sequential within a graph,
parallel across graphs |
|
Transactionality |
allOrNone at request or sObject
Collection level |
allOrNone at graph level, each
graph is transactional |
|
Structure |
Single compositeRequest array |
Multiple graphs, each with
compositeRequest array |
|
Dependency |
Subrequests can reference prior
outputs |
Subrequests within a graph can
reference outputs; graphs are independent |
|
Use Case |
Simple operations (e.g., create
Account + Contact) |
Complex, large-scale operations
(e.g., multiple related objects) |
|
Response Structure |
compositeResponse array |
graphs array with graphResponse
and compositeResponse |
|
Performance |
Slower for many subrequests due to
sequential execution |
Faster for complex operations due
to parallel graph execution |
When
to Use
- Composite Request:
- Use for simpler operations with fewer than 25
subrequests, such as creating a small number of related records (e.g., an
Account and a few Contacts).
- Suitable when you need to combine a few CRUD
operations or queries in a single call to reduce API usage.
- Example: Create an Account, then a Contact linked to
it, and query some related data.
- Composite Graph Request:
Comments
Post a Comment