Additional request inclusion behaviors

PATCHing and POSTing in a single request

When you execute a POST with request inclusion, the operation for each included resource must also be POST.

When you execute a PATCH with request inclusion, the operation for an included resource could be either POST or PATCH.

  • If you want to modify an existing resource and create a new related resource, the included resource's operation is POST.
  • If you want to modify an existing resource and modify an existing related resource, the included resource's operation is PATCH.

Requests succeed or fail as a unit

When a POST or PATCH uses request inclusion, it is possible that there could be a failure either of the operation on the root resource or the operation on any of the included resources. If any operation fails, the entire request fails and none of the objects are POSTed or PATCHed.

Included resources cannot reference resources other than the root resource

When using request inclusion, each included resource must specify its own operation and uri. The uri is expected to reference the root resource using the keyword this. This ensures that when the included resource is POSTed or PATCHed, the included resource is related to the root resource.

For example, suppose a POST is creating a claim and a note. The uri for the exposure would have a value such as "/claim/v1/claims/this/notes".

From a syntax perspective, you could attempt to attach an included resource not to the root resource, but rather to some other existing resource. For example, instead of referencing the root resource, the uri for the note could reference an existing claim, such as "/claim/v1/claims/cc:200/notes". This uri says "create a note and attach it not to the root resource of this POST, but rather to the existing claim cc:200".

The system APIs will not allow this. Any attempt to POST or PATCH an included resource to something other than the root resource will cause the operation to fail.