Working with API Filters

Index

• Overview
• Using Limit and Sort
• Using the Groups Parameter
• Field Filters
  • SQL-style Filters
  • Extended RegEx Filters
• The Advanced Fields
• Time Filters
  • Global Time Filters

Overview

Filters are a core component of working effectively with the Statseeker RESTful API. Filters can be applied to specify which resources (devices, interfaces, groups etc.) to report on, and can also be applied to specify a time-range for data collection and reporting.

Filters can be specifically applied by entering a filter statement, and/or by proxy through a combination of limit and {field}_sort keys.

[top]

Using Limit and Sort

All Statseeker API GET requests can contain both limit and {field}_sort keys. In combination these keys can be used to filter the contents of the response from the API.

The limit key is primarily included for use in pagination of the response in conjunction with the offset key (see Pagination for details), and can be employed to place a limit on the number of rows returned in the response data.

When not specified limit defaults to 50 and the response includes a links object which provides pagination by including links for:

• first – the first set of n rows, where n=limit
• prev – the previous set of n rows
• next – the next set of n rows
• last – the last set of n rows, where n≤limit

Example:

• https://your.statseeker.server/api/latest/cdt_cpu/ – limit isn’t specified so Statseeker will use the default and return 50 rows in the response
• https://your.statseeker.server/api/latest/cdt_cpu/?limit=5 – will return 5 rows
• https://your.statseeker.server/api/latest/cdt_cpu/?limit=5&offset=25 – will return rows 26 – 30

The {field}_sort parameter can be used to sort the rows prior to inclusion in the response. {field}_sort requires the specified field also be listed in the fields parameter. {field}_sort can be supplied as a comma separated list specifying the sort hierarchy and direction.

Examples:

• /api/latest/cdt_device/?fields=id,ipaddress&name_sort=1,desc

  The request will fail because we are attempting to sort on a field that has not been requested, (name is not included as a value in the fields parameter), won’t contained within the response data, and cannot be sort by

• /api/latest/cdt_device/?fields=id,ipaddress,name&name_sort=1,asc&limit=5

  Collect id, ipaddress and name details (fields=id,ipaddress,name)on all devices known to Statseeker, sort the devices alphabetically by name (name_sort=1,asc), and return details on the first five (limit=5)

This style of filtering becomes more useful when working with timeseries data, for example:

• /api/latest/cdt_cpu/?fields=deviceid,name,cpuLoad&cpuLoad_formats=avg&timefilter=range=now -15m to now&cpuLoad_sort=1,desc,avg&limit=5

  Return details (fields=deviceid,name,cpuLoad) on the 5 CPU objects (limit=5) with the highest average load (cpuLoad_sort=1,desc,avg) over the last 15 minutes

• /api/latest/cdt_device/?fields=id,ipaddress,name,ping_rtt&ping_rtt_formats=avg,vals&timefilter=range=now – 5m to now&ping_rtt_sort=1,desc,avg&limit=15

  Return device identification and ping RTT for the 15 devices with the highest average ping RTT over the last 15 minutes. Sort the results from highest to lowest average ping RTT.

[top]

Using the Groups Parameter

API requests can include a groups parameter which can be used to filter by the content of specified Statseeker groups. Multiple groups can be specified as a comma separated list of group IDs or names (e.g. groups=42505,42579 or groups=London Routers,Firewalls). Whether multiple groups are handled in an AND or OR (default) manner can be specified via the grouping_mode parameter.

Example:

• /api/latest/cdt_device/?fields=ipaddress,name&name_sort=1,asc&limit=5&groups=London,Routers&grouping_mode=AND

  Collect ipaddress and name details on all devices which appear both the London and Routers groups, sort the devices by name, and return details on the first five.

[top]

Field Filters

Field filters are applied at a field level to restrict the pool of resources that will be reported on and/or data returned. These filters use the format {field}_filter and accept either of an SQL-like query or an Extended Regular Expression (ERE). When providing an SQL-like query, the filter accepts both SQL operators (IS, LIKE, IN, BETWEEN, etc.) and wildcard characters (_ and %).

The field being filtered by must be included as a value of the fields parameter.

When your query is aggregating data, field filters can be applied both before and after data aggregation.

• {field}_filter – use in the absence of data aggregation, or apply prior to aggregation occurring
• {field}_post_filter – apply the filter after data aggregation has occurred

Examples: SQL-like Filters

Use the syntax:

• {field}_filter={operator}{value}
• {field}_filter={operator}(“{filter_string}”)

• https://your.statseeker.server/api/latest/cdt_device/?fields=id,ping_rtt&name_filter=LIKE("%25rtr")&ping_rtt_formats=vals&ping_rtt_sort=1,desc,avg&ping_rtt_timefilter=range%3Dnow%20-%205m%20TO%20now

  This request will fail because it attempts to filter on the name field, but name was not included in the list of fields to retrieve (fields=id,ping_rtt.)

• https://your.statseeker.server/api/latest/cdt_device/?fields=id,name,ping_rtt&name_filter=LIKE("%25rtr")&ping_rtt_formats=vals&ping_rtt_sort=1,desc,avg&ping_rtt_timefilter=range%3Dnow%20-%205m%20TO%20now

  Return identification data as well as ping return trip (ping_rtt) values for each ping request and the average trip time for all requests in the last 5 minutes. Filter the response data to only those devices with the string rtr in their name; this naming convention has been applied to all routers on the target network. Sort those results by average ping time from highest to lowest.

• https://your.statseeker.server/api/latest/cdt_device/?fields=name,ping_rttl&ping_rtt_formats=avg&ping_rtt_filter=>75&ping_rtt_filter_format=avg&ping_rtt_timefilter=range%3Dstart_of_today%20to%20now

  Return identification data as well as ping return trip (ping_rtt) values for each ping request, and the average trip time for all requests in the last 5 minutes. Filter the response data to only those devices with ping values greater than 75ms.

• https://your.statseeker.server/api/latest/cdt_device/?fields=name,ipaddress&ipaddress_filter=LIKE("10.100.44.%25")

  Return identification data for each device in the 10.100.44.0/24 subnet.

• https://your.statseeker.server/api/latest/cdt_device/?fields=id,name,ipaddress&ipaddress_filter=BETWEEN("10.100.44.0")%20AND%20("10.100.44.999")

  Return identification data for each device in the 10.100.44.0/24 subnet. The SQL BETWEEN operator will see an IP addresses as a string, so a final octet of .3 would be excluded from a range ending in .255. In our example we supplied a final octet of .999 to overcome this, and select all IP’s in the 10.100.44.0/24 subnet.

• https://your.statseeker.server/api/latest/cdt_device/?fields=id,name,ipaddress&ipaddress_filter=IN("10.100.44.11","10.100.44.12","10.100.44.13")

  Return identification data for each device listed in the filter.

[top]

Examples: ERE Filters

Use the syntax:

• {field}_filter=REGEXP'{filter_string}’

• https://your.statseeker.server/api/latest/cdt_device/?fields=id,name&name_filter=REGEXP%27rtr%27

  Return identification data for all devices with the string rtr in their name; this naming convention has been applied to all routers on the target network.

• https://your.statseeker.server/api/latest/cdt_device/?fields=name,ipaddress&ipaddress_filter=REGEXP'^10\.100\.44\.([0-9]|[1-9][0-9]|1([0-9][0-9])|2([0-4][0-9]|5[0-5]))$'

  Return identification data for each device in the 10.100.44.0/24 subnet.

[top]

The Advanced Fields

The Advanced fields option (fields_adv) is another resource level filter (applied to fields belonging to a specified resource/object), and is a way to specify fields and associated filters in a single parameter. When fields_adv is specified, the API will ignore any fields parameter key:value pair included in the same request, as well as any of the following associated fields:

The fields_adv can be used in place of the standard fields parameter, and can include all of the above fields as needed.

Example:

Return identification data, as well as ping return trip (ping_rtt) values and average value for the last 15mins, for each device known to Statseeker and sort these devices by the average ping, from highest to lowest

https://your.statseeker.server/api/latest/cdt_device/?fields_adv={"name":{"field":"name"},"id":{"field":"id"},"ipaddress":{"field":"ipaddress"},"ping":{"field":"ping_rtt","sort":{"priority":1,"order":"desc","format":"avg"},"formats":["avg","vals"],"timefilter":{"query":"range%3Dnow%20-%2015m%20TO%20now"}}}

When using the fields_adv parameter, the entire parameter is supplied in a JSON format and care should be taken when constructing this to ensure that:

• sort priority is provided as an integer (not bounded by quotes), and not as a string
• Values for the formats key are provided as an array (bounded in square brackets, [])
• The timefilter is provided as a couple of nested key:value pairs, i.e.key:{key:value}

[top]

Time Filters

Time filters are required when requesting any timeseries data from Statseeker, so must be included in any request where either of the fields or fields_adv parameters include a timeseries metric.

Timefilters should be specified in the following format:

The timefilter query string should be specified in the same format as that displayed in the Query Info field in the Console, or time filter in the Report editor. When forming complex time filters it may be useful to make use of the Advanced Time Filter Editor, and its Test functionality, to preview the scope of the resulting time period prior to passing the time filter in an API request. For more details on time filters, the Advanced Time Editor and testing time filters, see Time Filters.

[top]

Global Time Filters

Rather than specifying individual {field}_timefilter parameters for every timeseries metric being requested, you can provide a global parameter that is applied to all.

timefilter={timefilter_query_string}

Examples:

• URL Encoded: timefilter=range%3Dnow%20-15m%20TO%20now
• Raw: timefilter=range=now -15m to now

Any instance of {field}_timefilter will override the global setting for that specific field only.

[top]