Additional behaviors with write inclusion
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 an account and an AccountContact. The
uri for the AccountContact would have a value such as
"/account/v1/accounts/this/contacts".
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 AccountContact could reference an existing
account, such as "/account/v1/accounts/pc:20/contacts". This uri says
"create an AccountContact and attach it not to the root resource of this POST, but rather to
the existing account pc:20".
Cloud API 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.
Request inclusion response payload does not include child resources
When using request inclusion, the response payload just contains data about the root resource. Child resources that are POSTed or PATCHed are not included in the response. Information on child resources cannot be retrieved using query parameters in the initial request.
There are several ways to retrieve information on child resources that have been POSTed or PATCHed.
- Additional GET requests - Once you have successfully PATCHed or POSTed a child resource, retrieve information on that resource with a follow-up GET request.
- Using a composite request - Composite requests are an alternate method to execute multiple requests in a single call. The responses from each request are collected and returned in a single response payload. For more information, see Composite requests.
Request inclusion can use endpoints from different APIs
Some included resources can be manipulated using different APIs. For example, notes on an account are POSTed using the Account API, but notes are PATCHed using the Common API.
To POST a note, the method and uri fields look
like this:
"method": "post",
"uri": "/account/v1/accounts/<accountid>/notes"
To PATCH a note, the method and uri fields look
like this:
"method": "patch",
"uri": "/common/v1/notes/<noteid>"
However, some included resources are accessed through the same API as the root resource. For example, AccountContacts are POSTed and PATCHed through the Account API. POSTing an AccountContact as an included resource would use method and uri fields similar to this:
"method": "post",
"uri": "/account/v1/accounts/<accountid>/contacts"
PATCHing a contact would use method and
uri fields like this:
"method": "patch",
"uri":
"/account/v1/accounts/<accountid>/contacts/<contactid>"