The filter query parameter

Determining which fields you can filter on

For a given endpoint, there are several different ways to determine which fields you can filter on. The simplest is to run a query using a field you know to be invalid, such as GET ...?filter=dogsaregreat:eq:true. The resulting error message will provide a list of valid fields you can filter on, similar to this:

"message": "The field 'dogsaregreat' is not a filterable field for this endpoint. 
    The set of filterable fields is [accountNumber, accountStatus, createdDate]."

Another option that allows you to identify some of the attributes that are filterable is by reviewing the schema definition. If a field is filterable, then the schema definition includes the text: "filterable": true.

For example, the following is the schema description from Swagger UI for two fields returned by the Common API /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.

The limitation to the preceding option is that it won't display custom filters. You might have to look at the Gosu resource files to determine whether a customization has been added to make a field filterable. See Cloud API Developer Guide for information on custom filters and where to find them.

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

The filter query parameter cannot be used to construct OR criteria.

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 included resources

For information on how to use the filter parameter with included resources, see Query parameters for included resources.