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/..."
      }
    ]
  }
}
Java

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 and uri 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"
    }
  ]
}
Java

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.

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"
      }
    ]
  }
}
Java