Filtering Result Data

Using the q parameter

Sometimes when a large list of objects is returned from an operation you may want to filter the result, reducing the number of returned objects based on some meaningful condition. A filter is much like a SQL query where clause, allowing you to limit the number of returned data objects to only those that satisfy the criteria. To filter a list of returned data objects in the REST API you would use the q query parameter. Most REST API operations that return a list of data objects support filtering together with paging and sorting. By default there is no filter, q is null, and all results are returned.

For example, to call the GET method (used in the sorting example) to get the next set of 20 server requests but to limit them to only those that are performing poorly, and have an average response time of greater than 400ms, you would use the q parameter with the averageResponseTime attribute. The actual filter clause would be:

q=averageResponseTime>400

And, used together with the GET method in that example, it would look like:

/api/v1/requests?offset=60&limit=20&orderBy=averageResponseTime:desc&q=averageResponseTime>400

When using more than one filter clause, combining them with AND or OR (lowercase and or or is also acceptable), the q parameter requires parenthesis. For example, lets add to the previous call, an extra criterion of those server requests that also have at least two failed requests, where the failureCount attribute is 2 or greater:

/api/v1/requests?offset=60&limit=20&orderBy=averageResponseTime:desc&q=(averageResponseTime>400)AND(failureCount>=2)

Depending on the context from where you issue the query that contains the filter expression, you may need to replace white space with the %20 encoding. For example, if you execute a REST API query programmatically, say, from a Java class, then a filter expression containing a space need not encode that space. For example:

/api/v1/pages?q=(pageTitle LIKE '%AcmeHomePage%')

If the same query was executed from the command line, as you would with a cURL command, then the filter expression must use the %20 encoding:

/api/v1/pages?q=(pageTitle%20LIKE%20'%AcmeHomePage%')

If you're not sure, it is acceptable to always encode spaces.

Filter Expression Syntax

The formal syntax for the filter expression (the q parameter) is:

attribute op value [AND/OR attribute op value]*
where:
    attribute is:     a valid attribute name for the resource you are filtering (see next section)
    op is one of:     <, >, <=, >=, =, !=, LIKE, NOT LIKE, ILIKE, NOT ILIKE
    value is either:  a number or a single-quoted string

The filter expression can also scope to a particular Application (see Application Definitions overview). When including an application in a filter expression, the syntax above is extended:

WITHIN APPLICATION application-name
    This restricts the results to the named application.
    The application-name is an unquoted string.

WITHIN APPLICATION application-name FILTER BY filter-expression
    This first restricts the results to the named application application-name,
    and then runs the extra filter-expression over those results.

Some more examples of a filter expression may be the following (as explained above, note that you may need to replace white space with the %20 encoding):

/api/v1/pages?q=operationName like 'myOp%'
/api/v1/pages?q=WITHIN APPLICATION myApp
/api/v1/pages?q=WITHIN APPLICATION myApp FILTER BY operationName like 'myOp%'

Metadata Filter Attributes

Like with the orderBy parameter described earlier for sorting, you can find the different attribute names (and their data types) to use with the filter q parameter by querying the /metadata resource (the Get metadata operation) with the Filter type parameter. For example, if you wanted to know what are the attributes that you can filter by when retrieving server requests, Get Requests (which is the /requests resource), you can execute the following REST API query:

/api/v1/metadata/Filter/requests

This will list all the attributes which can then be used in the q parameter of the Get requests operation. The result list will look something the following, listing each attribute and type:

{
  ...
  "items" : [ {
    "name" : "minExternalTime",
    "type" : "LONG",
    "links" : [ ]
  }, {
    "name" : "loadRate",
    "type" : "LONG",
    "links" : [ ]
  }, {
    "name" : "isFlowStart",
    "type" : "BOOLEAN",
    "links" : [ ]
  }, {
    "name" : "failureCount",
    "type" : "LONG",
    "links" : [ ]
  }, {
  ...
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "api/v1/metadata/Filter/requests"
  } ],
  ...
}