Specifying the resources and fields to return
You can use query parameters to:
- Specify filtering criteria to narrow which resources are returned
- Specify which fields you want returned for the resources that are returned
Filtering GETs
You can narrow which resources are returned using the filter
keyword followed by
one or more criteria. The criteria are specified using the following syntax:
?filter=field:op:value
where:
- field is the name of a filterable field
- op is one of the comparison operators from the following table
- value is the value to compare
op value | Meaning | Example using the GET /activities endpoint | Returns activities where... |
eq |
Equal | ?filter=escalated:eq:true |
...the escalated field equals true |
ne |
Not equal | ?filter=escalated:ne:true |
...the escalated field equals false |
lt |
Less than | ?filter=dueDate:lt:2020-05-11T07::00::00.000Z |
...the due date is less than (before) May 11, 2020. |
gt |
Greater than | ?filter=dueDate:gt:2020-05-11T07::00::00.000Z |
...the due date is greater than (after) May 11, 2020. |
le |
Less than or equal | ?filter=dueDate:le:2020-05-11T07::00::00.000Z |
...the due date is less than or equal to (on or before) May 11, 2020. |
ge |
Greater than or equal | ?filter=dueDate:ge:2020-05-11T07::00::00.000Z |
...the due date is greater than or equal to (on or after) May 11, 2020. |
in |
In | ?filter=priority:in:urgent,high |
...the priority is either urgent or high |
ni |
Not in | ?filter=priority:ni:urgent,high |
...the priority is neither urgent nor high |
sw |
Starts with | ?filter=subject:sw:Contact%20claimant |
...the subject starts with the string "Contact claimant" |
cn |
Contains | ?filter=subject:cn:Contact%20claimant |
...the subject contains the string "Contact claimant" |
The query parameter is passed as part of a URL. Therefore, special conventions must be used for certain types of values to ensure the URL can be parsed correctly.
- Specify strings without surrounding quotes.
- If a string has a space in it, use the URL encoding for a space (%20). (For example,
"subject starts with 'Contact claimant'" is specified as
?filter=subject:sw:Contact%20claimant
) - If a string has a colon (:) in it, use two colons (::) in the URL. The first colon acts
as an escape character. (For example, "subject starts with 'Urgent: Information needed'" is
specified as
?filter=subject:sw:Urgent::Information%20needed
) - Specify Booleans as either true or false. (For example, "escalated is true" is specified
as
?filter=escalated:eq:true
) - Date and datetime fields must be specified as an ISO-8601 datetime value. All datetime
fields can accept either date values or datetime values. For datetime values, the colons in
the value must be expressed as "::". For example, "due date is less than
2020-04-03T15:00:00.000Z" is specified as
?filter=dueDate:lt:2020-05-11T07::00::00.000Z
.
References to typekey fields automatically resolve to the field's code. For example, to
filter on activities whose priority is set to urgent
, use: GET
/activities?filter=priority:eq:urgent
.
You can also use the filter query for related resources added through the
include
parameter. For more information, see Using query parameters on included resources.
Determining which values you can filter on
For a given endpoint, you can identify the attributes that are filterable by reviewing the
endpoint Model in Swagger UI. If a field is filterable, then the
schema description of the field includes the text: "filterable": true
.
For example, the following is the schema description for two fields returned by the Common
API's /activities
endpoint.
escalated boolean
readOnly: true
x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate string($date-time)
x-gw-nullable: true
Note that the escalated
field includes the "filterable":
true
expression, but the escalationDate
field does not. This
means that you can filter on escalated
, but not
escalationDate
.
When querying for a specific root resource, do not filter on the id
property
When writing a call to GET a single root resource, use an endpoint that returns a single element, such as:
GET /activities/xc:20
Do not attempt to retrieve the resource by using an endpoint that returns a collection and
filtering on the id
property, as in:
GET /activities?filter=id:eq:xc::20
Typically, the latter approach does not work because collection endpoints do not have
filterable id
properties.
This restriction applies to the root resource only. There may be situations where you need to retrieve a root resource and one or more child resources. When retrieving the child resources, it may be possible and appropriate to filter on the child resource's ID.
Filtering on multiple values
You can include multiple filter criteria. To do this, each criteria requires its own filter expression. Separate the expressions with an ampersand (&). The syntax is:
?filter=field:op:value&filter=field:op:value
When multiple criteria are specified, the criteria are ANDed together. Resources must meet all criteria to be included in the response. For example, the following GET returns only high priority activities that have not been escalated.
GET /activities?filter=priority:eq:high&filter=escalated:eq:false
Endpoints with default filters
Some endpoints have default filters. For example, the
/accounts/{AccountID}/jobs
endpoint has a default filter that returns
only open jobs.
You can identify whether an endpoint has a default filter by checking the endpoint summary in Swagger UI. The summary is visible after you click the GET button in Swagger UI for the given endpoint.
For example, the summary for the /accounts/{AccountID}/jobs
endpoint says: "Retrieve a list of jobs associated with this account. By default this will
include only open jobs."
You can use the filter
query parameter to override default
filters. For example, the following GET returns all jobs without regards to the status: GET
/accounts/{AccountID}/jobs?filter=jobFilter:eq:all
If you add a filter
query parameter on an endpoint with a default filter,
the default filter is discarded. If you want the response payload to reflect both the
default filter and a custom filter, you must specify both explicitly.
Tutorial: Send a GET with the filter
parameters
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.
- In Postman, start a new request by clicking the + to the right of the Launchpad tab.
- Specify Basic Auth authorization using user aapplegate and password gw.
- Enter the following and click Send:
GET
http://localhost:8180/pc/rest/common/v1/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:8180/pc/rest/common/v1/activities?filter=priority:eq:high
Checking your work
Compare the two payloads. Note that the first response payload includes all activities, whereas the second response payload contains only the activities with a high priority.
Specifying which fields to GET
Every endpoint returns a default set of fields. You can override this default set using the
fields
parameter. This is useful when you need properties not returned by
default, or when you want to avoid getting properties that are not necessary. (You can also
use the fields
query parameter for related resources added through the
include
parameter. For more information, see Using query parameters on included resources.)
The fields
parameter can be set to one or more of the following values:
*all
- Return all fieldsNote:*all
is not recommended for production environments as it returns fields that cost additional resources trimmed from default response payloads; instead, use the*default
filter with any specific fields that do not appear in the default detail or summary list.*default
- Return the default fields (typically used in conjunction with an additional field list)field_list
- Return one or more fields specified as a comma-delimited list
The set of fields returned by default
For endpoints that return a single element, the default fields to return are defined in a "detail" list. Similarly, for endpoints that return a collection, the default fields to return are defined in a "summary" list.
For example, the following list compares the detail fields for a contact
resource (for example, the default fields for the
/accounts/{accountId}/contacts/{contactId}
endpoint) and the summary
fields returned for a contact collection (for example, the default fields for the
/accounts/{accountId}/contacts
endpoint). Fields included in the Detail
only are in bold:
- Detail:
companyName
,contactSubtype
,displayName
,emailAddress1
,emailAddress2
,id
,industryCode
,primaryPhoneType
,subtype
,taxId
- Summary:
companyName
,contactSubtype
,displayName
,emailAddress1
,id
,industryCode
,subtype
,taxId
The fields
parameter has three options related to these default sets:
*detail
- Returns the fields in the detail list*summary
- Returns the fields in the summary list*default
- Returns the fields in the detail list (if the endpoint returns a single element) or the fields in the summary list (if the endpoint returns a collection)
For endpoints that return a single element:
?fields=*default
and?fields=*detail
are logically equivalent.- You can override the default behavior by using
?fields=*summary
, which returns the summary fields instead of the detail fields.
For endpoints that return a collection:
?fields=*default
and?fields=*summary
are logically equivalent.- You can override the default behavior by using
?fields=*detail
, which returns the detail fields instead of the summary fields.
Some API calls need a set of fields that is not exactly equivalent to either the detail list or the summary list. These calls can name specific fields, either on their own or in addition to a default list of fields. They can also specify all fields.
Returning the default properties plus additional specific properties
To return the default fields of an endpoint with an additional set of fields, use:
?fields=*default,field_list
where field_list
is a comma-delimited list of fields.
For example, the following query returns all default fields for activity xc:20 as well as the description and the start date.
GET /activities/xc:20?fields=*default,description,startDate
Returning a specific set of properties
To return a specific set of fields, use:
?fields=field_list
where field_list
is a comma-delimited list of fields.
For example, the following query returns only the description and the start date for activity xc:20:
GET /activities/xc:20?fields=description,startDate
Returning a specific set of properties on inlined resources
Some response payloads include inlined resources in the attributes
section. For example, the following is a snippet of the response for a GET
/activities
. This payload contains two inline resources,
assignedGroup
and assignedUser
.
"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},
"closeDate": "2020-04-06T07:00:00.000Z",
"dueDate": "2020-04-06T07:00:00.000Z",
"escalated": false,
"id": "cc:20",
...
}
You can use the fields
query parameter to specify an inlined resource.
When you do, all default fields for that resource are returned. For example, you could
specify that you want a GET /activities
to return only the
assignedGroup
and assignedUser
fields (and all of their
default subfields) using the following:
GET /activities?fields=assignedGroup,assignedUser
This would return:
"attributes": {
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
}
}
You can also specify specific subfields using the following syntax:
?fields=inlinedResourceName.fieldName
For example, you could specify that you want a GET /activities
to return
only the IDs of the assigned user and group using the following:
GET /activities?fields=assignedGroup.id,assignedUser.id
This would return:
"attributes": {
"assignedGroup": {
"id": "demo_sample:31"
},
"assignedUser": {
"id": "demo_sample:1"
}
}
Returning all properties
To return all of the fields that an endpoint is configured to return, use:
?fields=*all
For example, the following query returns all the possible fields for activity xc:20.
GET /activities/xc:20?fields=*all
Note that the *all
query parameter returns all fields that the caller is
authorized to view. If there are fields on a resource that a caller is not authorized to
view, they are excluded from queries using the *all
query parameter.
Tutorial: Send a GET with the fields
parameter
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:8180/pc/rest/common/v1/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:8180/pc/rest/common/v1/activities?fields=id,subject
Checking your work
Compare the two payloads. Note that the first response payload includes the default fields
for activities, whereas the second response payload includes only the id
and subject
fields.