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 claim/v1/claims/demo_sample:1?include=activities &fields=activities:id,dueDate
- Returns: Claim demo_sample:1 and its included activities. For the
activities, return only
id
anddueDate
.
The filter
parameter
You can filter out included resources that do not meet a given criteria.
- Syntax:
filter=resource:field:op:value
- Example:
GET claim/v1/claims/demo_sample:1?include=activities &filter=activities:escalated:eq:true
- Returns: Claim demo_sample:1 and its included activities that have been escalated
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 claim/v1/claims/demo_sample:1?include=activities &sort=activities:dueDate
- Returns: Claim demo_sample:1 and its included activities, sorted by their due date.
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 claim/v1/claims/demo_sample:1?include=activities &pageSize=activities:5
- Returns: Claim demo_sample:1 and up to 5 of its included activities.
The includeTotal
parameter
You can include the total number of included resources.
- Syntax:
includeTotal=resource:true
- Example:
GET claim/v1/claims/demo_sample:1?include=activities &includeTotal=activities:true
- Returns: Claim demo_sample:1, its included activities, and the total number of included activities for demo_sample:1.
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 claims, with the main contact and reporter included. For claims, you want only the id and claim number fields. For the main contact, you want only the id, display name, and primary phone fields. For the reporter, you want only the display name field. To get this response, you must send the following:
GET /claims?include=mainContact,reporter
&fields=id,claimNumber
&fields=mainContact:id,displayName,primaryPhone
&fields=reporter: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
- In Postman, start a new request by clicking the + to the right of the
Launchpad tab.
- On the Authorization tab, select Basic Auth using user aapplegate and password gw.
- Enter the following and click Send:
GET
http://localhost:8080/cc/rest/claim/v1/claims?include=activities
- Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
- Enter the following and click Send:
GET
http://localhost:8080/cc/rest/claim/v1/claims?fields=id,claimNumber&include=activities&filter=activities:escalated:eq:true
Checking your results
Compare the two payloads. Note the following differences:
In the first payload:
- For claims, the default claim fields are returned.
- For activities, all activities are returned.
In the second payload:
- For claims, only the
id
andclaimNumber
fields are returned. - For activities, only the escalated activities are returned.
In the first payload:
- For accounts, the default account fields are returned.
- For contacts, all contacts are returned.
In the second payload:
- For accounts, only the
id
and theaccountNumber
fields are returned. - For contacts, only the contacts that are marked as primary payers are returned.