Using query parameters on 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.

Specifying query parameters that apply to an included resource

The general pattern for query expressions on included resources is to specify the included resource name somewhere in the expression's value. For example, the following call gets all activities assigned to the current user and any related notes. The number of notes returned is limited to 5.

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

Included resources and primary resources

Query expressions for included resources are independent of query expressions for primary resources. There could be a query expression for primary resources only, for included resources only, or for both. For example, the following three queries all return activities and their related notes. But, the impact of the pageSize parameter varies.

  • GET /activities?pageSize=7&include=notes
    • The response is limited to 7 activities.
    • There is no limit on notes.
  • GET /activities?include=notes&pageSize=notes:5
    • There is no limit on activities.
    • The response is limited to 5 notes per activity.
  • GET /activities?pageSize=7&include=notes&pageSize=notes:5
    • The response is limited to 7 activities.
    • The response is limited to 5 notes per activity.

Included resources and other included resources

Query expressions for each included resource are also independent of query expressions for other included resources. If a given GET includes multiple included resources and you want to apply a given query expression to all included resources, you must specify the query expression for each included resource.

For example, suppose you want to GET all accounts. But you want the response payload to include only the account holder and other contacts, and you want only the id and subtype for these contacts. To get this response, you must send the following:

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

Note that, in this example, the logic to restrict the returned fields to only id and subtype needs to be specified for each included resource.

Summary of query parameters for included resources

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 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 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.

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.
  2. Specify Basic Auth authorization using user aapplegate and password gw.
  3. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?included=notes

  4. Open a second request tab and specify Basic Auth authorization using user aapplegate and password gw.
  5. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?included=notes&fields=id,subject&filter=notes:escalated

Checking your results

Compare the two payloads. Note the following differences:

In the first payload:

  • For activities, the default activity fields are returned.
  • For notes, all notes are returned.

In the second payload:

  • For activities, only the id and subject fields are returned.
  • For notes, only the escalated notes are returned.