Filtering provides a way to limit the response from most API methods that return lists based on a set of criteria. The criteria is specified in the optional filterString query parameter and there may only be one filter string per request but a single filter string may have multiple filters. Where more than one filter is specified in a filter string, all filters must be satisified for an item to be included in the response.
The filter keywords are taken from the fields in the response. Thus a Forum element has a name, summary, status and lists of moderators and participants. Any of those may be used as filter keywords as the following example shows:
In the example, the filter string is "name has 'windows'". The name portion is the keyword, 'has' is an operator that performs a case-insensitive search within the data referenced by the keyword and 'windows' is the text to search for within the data. The result of the filter will be to limit the list of forums returned from the directory to just those which contain the word 'windows' in its name.
Another example shows how to filter by date range.
Here, the '>' operator is used to return any message posted on or after 10th June 2017 in the specified topic.
Each keyword has a specific type and the value in the filter must match those types. The API Documentation shows the keyword type information.
String types require a value which is a string, specified with either single or double quotes. The quote character used at the start of the string must match the character at the end. The quotes are not part of the string value itself.
Number types require a value which is a number expressed as digits. Negative values are not supported.
Date types require a value expressed as a date without quotes. The format is generally YYYY-MM-DDTHH:mm:SS where YYYY is the four digit year, MM is the month, DD is the day, HH is the hour, mm is the minutes and SS are the seconds. Values do not need to be zero padded so either 06 or 6 is valid to express a month. When using a date to match a range be aware that the equality operator cannot be used since the matching resolution is to the second. Where parts of the date value are omitted, either '1' or '0' is assumed as appropriate. Thus 2017-02-10T14 is treated as 14:00:00.
Boolean types require the value to be either true or false.
Enumeration types require their actual enumerated name as the value. Refer to the API Documentation for the list of values. The enumerated name may be expressed in either upper or lower case and must not be surrounded in quotes.
The following set of operators are available for use with filter keywords. Note that not all operators are available with every keyword. The type of the keyword limits which operator can be legally applied to it.
|=||Equals||Strings, booleans, enumerations or numbers|
|>||Greater than||Numbers or dates|
|<||Less than||Numbers or dates|
|not||Negator||Negates the next operator|
|has||Contains||Strings or arrays|
As a special note, the 'not' operator is always followed by another operator and negates that operator. Thus 'not =' returns all items that do not match the criteria, and 'not has' returns all items where the criteria does not occur in a string or array.
The table below shows some example filters together with an explanation.
|summary has 'windows'||Matches any forum where the summary field contains the word 'windows'. Note that the match is always case insensitive.|
|status = OPEN||Matches any forum which is open. Other values are CLOSED and PRIVATE. Note that enumeration values should not be in quotes.|
|moderator has 'spalmer'||Matches any forum where spalmer is listed as one of the moderators.|
|name has 'windows', summary not has 'oracle'||An example of a compound filter which matches a forum with 'windows' in the name but no 'oracle' in the summary.|
|datetime > 2017-02-15||Matches all messages posted after 15th February 2017|
|read = false||Matches all messages that have not yet been read|