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
  • An account and its AccountLocations

When using request inclusion for simple parent/child relationships, the JSON has the following structure. This structure is used when the root resource and the included resource are being POSTed. If the root resource is being PATCHed, the structure may differ slightly. For more information, see PATCHes in request inclusion. 

{
  "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 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 /activities call to create an activity and a note for that activity. The note is the included resource. The included section would contain code similar to this:

"included": {
  "Note": [
    {
      "attributes": {
          ...
      },
      "method": "post",
      "uri": "/common/v1/activities/this/notes"
    }
  ]
}

This specifies that in order to create the note, use the POST /common/v1/activities/{activityId}/notes endpoint.

The uri must start with the API name, such as "/common/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 does not use this. For more information, see PATCHes in request inclusion.

Example of request inclusion for simple parent/child relationships

The following payload is an example of creating an activity on account pc:10, and a note for that activity.

POST http://localhost:8180/pc/rest/account/v1/accounts/pc:10/activities

{
  "data": {
    "attributes": {
      "activityPattern": "general_reminder"
    }
  },
  "included": {
    "Note": [
      {
        "attributes": {
            "subject": "Initial phone call",
            "body": "Initial phone call with claimant"
        },
        "method": "post",
        "uri": "/common/v1/activities/this/notes"
      }
    ]
  }
}