Query parameters for included resources

Some endpoints support the ability to query for a given type of resource and for resource types related to that type. For example, by default, the GET /activities endpoint returns only activity resources. However, you can use the include query parameter to include any notes related to the returned activities in the response payload. These types of resources are referred to as included resources. The technique of adding included resources to a GET is sometimes referred to as response inclusion or read inclusion.

The syntax for adding included resources is:

?include=<resourceName>

For example GET /activities?include=notes returns all activities assigned to the current caller, and all notes associated with those activities.

For more information on the default behavior of include, see Payload structure for a response with included resources.

Most query parameters that can be used on primary resources can also be used on included resources.

Syntax for query parameters for included resources

To specify that a query parameter operates on an included resource, use the following syntax:

<queryParameter>=<includedResource>:<queryValue>

For example, the following GET retrieves activities and their notes. It also specifies that the number of notes to return is limited to 5.

GET /activities?include=notes
               &pageSize=notes:5

The following GET retrieves activities and their notes. It also specifies that the only fields to return for the notes are id and subject.

GET /activities?include=notes
               &fields=notes:id,subject

Summary of query parameters for included resources

The fields parameter

You can specify which fields you want returned in the included resources.

  • Syntax: fields=resource:field_list
  • Example: 
    GET policy/v1/policies/pc:10?include=contacts
           &fields=contacts:licenseState,licenseNumber
  • Returns: Policy pc:10 and its included contacts. For the contacts, return only licenseState and licenseNumber.

The filter parameter

You can filter out included resources that do not meet a given criteria.

  • Syntax: filter=resource:field:op:value
  • Example: 
    GET policy/v1/policies/pc:10?include=contacts
           &filter=contacts:maritalStatus:eq:S
  • Returns: Policy pc:10 and its included contacts that have a marital status of "S" (single)

The sort parameter

You can sort the included resources. This sorting is reflected in both the payload's related sections and the included section.

  • Syntax: sort=resource:properties_list
  • Example: 
    GET policy/v1/policies/pc:10?include=locations
           &sort=locations:locationNum
  • Returns: Policy pc:10 and its included locations, sorted by their location number.

The pageSize parameter

You can specify a maximum number of included resources per root resource. Also, when you use pageSize on included resources, there are no prev and next links at the included resource level.

  • Syntax: pageSize=resource:n
  • Example: 
    GET policy/v1/policies/pc:10?include=contacts
           &pageSize=contacts:5
  • Returns: Policy pc:10 and up to 5 of its included contacts.

The includeTotal parameter

You can include the total number of included resources.

  • Syntax: includeTotal=resource:true
  • Example: 
    GET policy/v1/policies/pc:10?include=contacts
           &includeTotal=contacts:true
  • Returns: Policy pc:10, its included contacts, and the total number of included contacts for pc:10.

Specifying query parameters at different levels

Specifying query parameters for both parent and included resources

You can specify query parameters for both a parent and included resources in the same GET. To do this, you must specify a separate query expression for each parameter used at the parent level and for each parameter used at the included resource level.

For example, the following query retrieves activities and their notes. For activities, only the id, description, and dueDate fields are returned. For notes, only the id and subject are returned.

GET /activities?include=notes
               &fields=id,description,dueDate
               &fields=notes:id,subject

You can also use different query parameters for each resource. For example, the following query retrieves activities and their notes. For activities, only the id, description, and dueDate fields are returned. For notes, the number of notes per activity is limited to 5.

GET /activities?include=notes
               &fields=id,description,dueDate
               &pageSize=notes:5

Specifying query parameters for multiple types of included resources

You can also specify multiple types of included resources and specify different query parameters for each resource.

For example, suppose you want to GET all accounts, with the account holder and other contacts included. For the account, you want the id and account number fields. For the account holder, you want the id and the display name. For the other contacts, you want only the display name field. To get this response, you must send the following:

GET /accounts?include=accountHolder,contacts
             &fields=id,accountNumber
             &fields=accountHolder:id,displayName
             &fields=contacts:displayName

Tutorial: Send a GET with query parameters for included resources

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/policy/v1/policies?include=contacts

  3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  4. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/policy/v1/policies?include=contacts&fields=id,policyNumber&filter=contacts:contactSubtype:eq:company

Checking your results

Compare the two payloads. Note the following differences:

In the first payload:

  • For policies, the default claim fields are returned.
  • For contacts, all contacts are returned.

In the second payload:

  • For policies, only the id and policyNumber fields are returned.
  • For policies, only the company contacts are returned (and not the person contacts).