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/..."
      }
    ]
  }
}
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 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 method and uri fields

Request inclusion involves a single call to a single endpoint. But internally, Cloud API uses 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"
    }
  ]
}
Java

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