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 /claims endpoint has a default filter that returns only claims assigned to the caller making the API call.

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 /claims endpoint says: "Retrieve a list of claims, by default those assigned to the current user."

You can use the filter query parameter to override default filters. For example, if you are a caller who is authorized to view claims not assigned to you (such as the super user su), the following GET returns claims assigned to Betty Baker: GET claims?filter=assignedUser:eq:demo_sample::8

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

  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. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  3. Specify Basic Auth authorization using user aapplegate and password gw.
  4. Enter the following and click Send:

    GET http://localhost:8080/cc/rest/common/v1/activities

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

    GET http://localhost:8080/cc/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 fields
    Note: *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 claim resource (for example, the default fields for the /claims/{claimId} endpoint) and the summary fields returned for a claim collection (for example, the default fields for the /claims endpoint). Fields included in the Detail only are in bold:

  • Detail: assignedGroup, assignedUser, assignmentStatus, claimNumber, description, faultRating, flagged, id, incidentOnly, insured, jurisdiction, lobCode, lossCause, lossDate, lossLocation, lossType, mainContact, policyAddresses, policyNumber, reportedByType, reportedDate, reporter, segment, state, strategy, validationLevel
  • Summary: assignedGroup, assignedUser, assignmentStatus, claimNumber, faultRating, flagged, id, incidentOnly, insured, jurisdiction, lobCode, lossCause, lossDate, lossType, mainContact, policyNumber, reportedByType, reportedDate, reporter, segment, state, strategy, validationLevel

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

  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:8080/cc/rest/common/v1/activities

  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:8080/cc/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.