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 account has an "account holder". This is an AccountContact who is the legal holder of the account. An account can have any number of child AccountContacts, but only one of those AccountContacts can be labeled as the account holder.
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 /accounts
call to
create an account and an AccountContact who is the "accountHolder". The AccountContact is
the included resource. The included
section would contain code similar to
this:
"included": {
"AccountContact": [
{
"attributes": {
...
},
"refid": "...",
"method": "post",
"uri": "/account/v1/accounts/this/contacts"
}
]
}
This specifies that in order to create the AccountContact, use the POST
/account/v1/{accountId}/contacts
endpoint.
The uri must start with the API name, such as "/account/v1".
If the included resource is being POSTed, 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. If the root
resource is being PATCHed, the URI field would not use this
. For more
information, see PATCHes in request inclusion.
Example of request inclusion for named relationships
The following payload is an example of creating an account and an AccountContact for the account whose relationship is "accountHolder". (Accounts also require a primary location, so the payload also creates an AccountLocation whose relationship is "primaryLocation".) For more information on creating accounts, see Creating an account.
POST http://localhost:8180/pc/rest/account/v1/accounts
{
"data": {
"attributes": {
"accountHolder": {
"refid": "newperson"
},
"organizationType": {
"code": "individual"
},
"preferredCoverageCurrency": {
"code": "USD"
},
"preferredSettlementCurrency": {
"code": "USD"
},
"primaryLocation": {
"refid": "newloc"
},
"producerCodes": [
{
"id": "pc:6"
}
]
}
},
"included": {
"AccountContact": [
{
"attributes": {
"contactSubtype": "Person",
"firstName": "Bill",
"lastName": "Preston",
"primaryAddress": {
"addressLine1": "2850 S Delaware St #400",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"method": "post",
"refid": "newperson",
"uri": "/account/v1/accounts/this/contacts"
}
],
"AccountLocation": [
{
"attributes": {
"locationCode": "0001",
"locationName": "Location 0001",
"nonSpecific": true,
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"method": "post",
"refid": "newloc",
"uri": "/account/v1/accounts/this/locations"
}
]
}
}