Expandable Resources

New standard of Core API endpoints will have the ability to expand sub resources for certain business data objects such as customers, order etc. This can be done by adding ?expand=sub_resource_name field to the URL. Normally, without the expand field parameter set the response will look like below:

{
  "resources": [
    {
      "externalId": "John-Doe-dec71345-61bc-429a-bc02-2095360e71da",
      "uuid": "be291b84-4eba-48f9-9613-2cd706c14512",
      "firstName": "John",
      "lastName": "Doe",
      "prefix": "Mr.",
      "suffix": "",
      "disabled": false,
      "image": "",
      "dateCreated": "2021-08-23T16:23:03Z",
      "dateModified": "2021-08-23T16:23:03Z",
      "attributes": [],
      "addresses": ["address-uuid"],
      "emailAddresses": ["email-address-uuid"]
      ...
    },
    ...
  ]
}

As you can see expandable resources like addresses and emailAddresses will be populated with UUIDs. This UUID will map to a resource location in the backend so if you can ask to expand the particular resource through the expand field to view the data inside that resource. Below is an example if you used the expand field to access the address sub resource:

{
  "resources": [
    {
      "externalId": "John-Doe-dec71345-61bc-429a-bc02-2095360e71da",
      "uuid": "be291b84-4eba-48f9-9613-2cd706c14512",
      "firstName": "John",
      "lastName": "Doe",
      "prefix": "Mr.",
      "suffix": "",
      "disabled": false,
      "image": "",
      "dateCreated": "2021-08-23T16:23:03Z",
      "dateModified": "2021-08-23T16:23:03Z",
      "attributes": [],
      "addresses": [
         {
           "uuid": "address-uuid",
           "city": "example-city", 
           //other fields...
         }
      ],
      "emailAddresses": ["email-address-uuid"]
      ...
    },
    
    ]
}

Expanding Multiple Subresources#

If you want to expand multiple different types of subresrouces, you can do so by comma-delimitting the subresrouces names that are passed into the expand query parameter.

For example: ?expand=importantDates,emailAddresses,addresses

If you want to expand all possible subresources in a resource you can do so by providing passing all in the expand query parameter.

For example: ?expand=all

Note: All sub resources are capped at 100. (ie. only a max of 100 addresses)

Getting granular: Recursion#

Supports recursion using dot-notation (i.e. addresses.country) to access certain field under a sub resource.

Note: Recursive sub resource expansion be capped at 1 level.

Multiple Resources: Pagination#

For paginated results, sub resources are prefixed with resources (i.e. expand=resources.addresses)

Expand All Subresources#