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".