Request and response inclusion
Inclusion is a way of accessing both a parent resource and resources relating to that parent in one command. The availability of inclusion depends on the resource, and can be available for both requests and responses.
Request inclusion
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.
The parent resource is often referred to as the root resource. The root
resource is specified in the payload's data
section. The related resources
are specified in the payload's included
section.
For example, a caller can use a single POST /accounts
to
create a new account, a set of AccountContacts for that account, a set of AccountLocations
for that account, and a set of documents for that account.
In order to use request inclusion, the following must be true:
- There must be a POST or PATCH endpoint for the root resource.
- This endpoint must have the child resource as part of its
included
section. - There must also be a POST or PATCH endpoint for the child resource.
The syntax for request inclusion varies slightly, depending on whether the relationship between the root resource and the included resource is a "simple parent/child relationship", or a "named relationship".
Request inclusion can use endpoints from different APIs for included resources.
Response inclusion
Some endpoints allow you to use query parameters to include information about related resources in the response. See Additional behaviors with read inclusion and Payload structure for a response with included resources for more information.