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 /claims
to create a
new claim, a set of ClaimContacts for that claim, a set of incidents for that claim, and a set
of exposures for that claim.
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".
Syntax for simple parent/child relationships
In most cases, the relationship between the root resource and an included resource is a simple parent/child relationship. Examples of this include:
- An activity and its notes
- A claim and its incidents
When using request inclusion for simple parent/child relationships, the JSON has the following structure:
{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"method": "post",
"uri": "/../this/..."
}
]
}
}
The data
section
The data
section includes information about the root resource, such as its
attributes
. (For PATCHes, the data
section could also
include a checksum value for the root resource.)
The included
section
The included
section consists of one or more subsections of included
resources. Each subsection starts with the resource type name. Then, one or more resources
of that type can be specified. For each resource, you must specify:
- The resource's
attributes
- The
method
anduri
to create or modify the resource.
The method
and uri
fields
Request inclusion involves a single call to a single endpoint. But internally, the system APIs use multiple endpoints to execute the call. For every included resource, you must specify the operation and uri relevant to that resource.
For example, suppose you are writing a POST /claims call to create a claim and
a note. The note is the included
resource. The included section would
contain code similar to this:
"included": {
"Note": [
{
"attributes": {
...
},
"method": "post",
"uri": "/claim/v1/claims/this/notes"
}
]
}
This specifies that in order to create the note, use the POST
/claim/v1/claims/{claimId}/notes
endpoint.
The uri must start with the API name, such as "/claim/v1".
The uri must also specify the ID of the root resource. When the root resource and the
included resources are being created at the same time, the root resource does not yet have
an ID. Therefore, the keyword this
is used in the uri to represent the root
resource's ID.
Example of request inclusion for simple parent/child relationships
The following payload is an example of creating a claim and a note for the claim. The payload assumes there is an existing policy whose number is "FNOL-POLICY". For more information on creating policies, see Executing FNOL.
POST http://localhost:8080/cc/rest/claim/v1/claims
{
"data" : {
"attributes": {
"lossDate": "2020-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY"
}
},
"included": {
"Note": [
{
"attributes": {
"subject": "Initial phone call",
"body": "Initial phone call with claimant"
},
"method": "post",
"uri": "/claim/v1/claims/this/notes"
}
]
}
}
Syntax for named relationships
In some cases, the relationship between the root resource and an included resource is more than just a parent/child relationship. It is a "named relationship" in which the relationship has a special designation or label.
For example, every claim has a "reporter". This is the ClaimContact who first reported the claim to the insurer. A claim can have any number of child ClaimContacts, but only one of those ClaimContacts can be labeled as the reporter.
When using request inclusion for named relationships, the JSON has the following structure. The lines that are not required for simple parent/child relationships but are required for named relationships appear in bold:
{
"data" : {
"attributes": {
"<relationshipField>": "<arbitraryRefId>"
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"refid": "<arbitraryRefId>",
"method": "post",
"uri": "/../this/..."
}
]
}
}
The data
section
The data
section includes information about the root resource, such as its
attributes
. (For PATCHes, the data
section could also
include a checksum value for the root resource.)
The data
section also includes the field that names the relationship with
the child resource. This field is set to some reference ID. The value of this reference ID
is arbitrary. It can be any value, as long as the value also appears with the child resource
in the included
section.
The included
section
The included
section consists of one or more subsections of included
resources. Each subsection starts with the resource type name. Then, one or more resources
of that type can be specified. For each resource, you must specify:
- The resource's
attributes
- The
method
anduri
to create or modify the resource.
The refid
field
Each included
resource must include a refid
field. This
field must be set to the same arbitrary reference ID used in the data
section. The system APIs use refids to identify which child resource in the
included
section has the named relationship with the root resource.
The method
and uri
fields
Request inclusion involves a single call to a single endpoint, but the system APIs internally use multiple endpoints to execute the call. For every included resource, you must specify the operation and uri relevant to that resource.
For example, suppose you are writing a POST /claims call to create a claim and
a ClaimContact who is the "reporter". The ClaimContact is the included
resource. The included section would contain code similar to this:
"included": {
"ClaimContact": [
{
"attributes": {
...
},
"refid": "...",
"method": "post",
"uri": "/claim/v1/claims/this/contacts"
}
]
}
This specifies that in order to create the ClaimContact, use the POST
/claim/v1/claims/{claimId}/contacts
endpoint.
The uri must start with the API name, such as "/claim/v1".
The uri must specify the ID of the root resource. When the root resource and the included
resources are being created at the same time, the root resource does not yet have an ID.
Therefore, the keyword this
is used in the uri to represent the root
resource's ID.
Example of request inclusion for named relationships
The following payload is an example of creating a claim and a ClaimContact for the claim whose relationship is "reporter". The payload assumes there is an existing policy whose number is "FNOL-POLICY". For more information on creating policies, see Executing FNOL.
POST http://localhost:8080/cc/rest/claim/v1/claims
{
"data" : {
"attributes": {
"lossDate": "2020-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"reporter": {
"refid": "robertFarley"
}
}
},
"included": {
"ClaimContact": [
{
"attributes": {
"firstName": "Robert",
"lastName": "Farley",
"contactSubtype": "Person"
},
"refid": "robertFarley",
"method": "post",
"uri": "/claim/v1/claims/this/contacts"
}
]
}
}
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.