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 in ClaimCenter
  • An account and its AccountLocations in PolicyCenter
  • A user role and its permissions in BillingCenter

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, in ClaimCenter, 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 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".

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 a new role in BillingCenter and associating a permission with that role:

POST http://localhost:8580/bc/rest/admin/v1/roles
        
{
  "data": {
    "attributes": {
        "name": "Region manager"
    }
  },
  "included": {
     "RolePermission": [
         {
             "attributes": {
                "permission": {
                    "code": "regionmanage"
                }
             },
             "method": "post",
             "uri": "/admin/v1/roles/this/permissions"
         }
     ]
  }
}