Cisco Prime Infrastructure API
Prime Infrastructure API Documentation

# Using Filtering

Filtering lets you limit the results of a request based on the value of specific Resource attributes. Check the documentation for each request type to see if it supports Filtering.

## Filtering Syntax

Filtering on a given attribute of a resource is simple. The documentation gives a list of all attributes for a given resource. For example, to get a device with a given IPAddress, you may use the following:

    	../webacs/api/v1/data/Devices?ipAddress="192.168.1.1"

A set of operators allows you to refine the filter in many ways. For example, to get the list of all device in a given subnet, you may use the startsWith operator on the IPAddress:

    	../webacs/api/v1/data/Devices?ipAddress=startsWith("192.168.")

The results of a query can be filtered using the value of one or more attribute. These criteria can be ' ANDed' (the default) or ' ORed' together. So to get all devices in private subnets, you may use an ORed request as follows:

    	../webacs/api/v1/data/Devices?.or_filter=true&ipAddress=startsWith("192.168.")&ipAddress=startsWith("10.0.")

Note that multiple requests return nested types. To filter on a nested attribute value, you can use a "dotted" notation to each attribute name. For example, to filter a response on one of the MAC addresses of a Device, you may use the following URL:

    	../webacs/api/v1/data/InventoryDetails?.full=true&ethernetInterface.macAddress="000d29f0d2b6"

## Case Sensitivity

The query parameter .case_sensitive controls whether string comparisons are case sensitive or not. When .case_sensitive is present in the url and set to true, string comparisons are case sensitive. When .case_sensitive is not present in the url or is set to false, string comparisons are case IN-sensitive

For example, the four urls below are case IN-sensitive and will return the same result:

                                ../api/v1/data/Devices?deviceName=IFM&.case_sensitive=false
                                ../api/v1/data/Devices?deviceName=ifm&.case_sensitive=false
                                ../api/v1/data/Devices?deviceName=IFM
                                ../api/v1/data/Devices?deviceName=contains("IFM")
                                ../api/v1/data/Devices?deviceName=ifm

Whereas, the two urls below are case sensitive and will return different results

                                ../api/v1/data/Devices?deviceName=IFM&.case_sensitive=true
                                ../api/v1/data/Devices?deviceName=ifm&.case_sensitive=true

## Filtering Operators

Operators are allowed on attributes depending on their types. The following operators can be used in the filter definitions:

|  | AppliesTo |
--- | --- | --- | ---
Function | Name | Numeric | Enum | Boolean | String | Date | Comment
(literal) | equals | * | * | * | * | * | Same as eq()
eq(value) | equals | * | * | * | * | * |
ne(value) | not equals | * | * | * | * | * | Inverse of eq()
in(value1,value2...) | in | * | * |
gt(value) | greater than | * |  | * | * |
ge(value) | greater or equal to | * |  | * | * |
lt(value) | less than | * |  | * | * |
le(value) | less than or equal to | * |  | * | * |
between(start,finish) | between two values | * |  | * | Both values must be same type
contains(value) | contains |  | * |
notContains(value) | does not contain |  | * |
startsWith(value) | starts with |  | * |
notStartsWith(value) | does not start with |  | * |
endsWith(value) | ends with |  | * |
notEndsWith(value) | does not end with |  | * |
isTrue() | is true |  | * |
isFalse() | is false |  | * |
isEmpty() | collection property is empty | * | * | * | * | * | Applies to collection properties only
notIsEmpty() | collection property is not empty | * | * | * | * | * | Applies to collection properties only
isNull() | property is null |  | * |  | Note that this is not the same as eq("")
notIsNull() | property is not null |  | * |

# Filtering based on Dates

When filtering based on date, you must specify the date in ISO-8601 format. Additionally, you should surround the date with quotes.

Some examples:

    	../webacs/api/v1/data/Alarms?alarmFoundAt=gt("2012-06-20T00:01:00")
    	../webacs/api/v1/data/Alarms?alarmFoundAt=lt("2012-06-20")
    	../webacs/api/v1/data/Alarms?alarmFoundAt=between("2012-06-01","2012-07-01")

# Domain Based Filtering

In Prime Infrastructure, there is a concept of "Virtual domains" which limits a users' access to a set of network objects based on their location. The API respects this concept, in that basic requests are filtered by the users' "default" domain as defined in Prime Infrastructure. Within a session it is possible to change the domain that is being used through use of the control parameter :

    			 ?_ctx.domain="otherDomain"

This changes the current domain until the session ends, or the user set the domain though another query using this control parameter.

# Group Based Filtering

In NCS, there is a concept of "Groups" which allow devices to be grouped together with like items. There are various types of groups including sites and other user defined groups. It is possible to limit the results returned using one or more of these groups.

For example:

    			 ?.group=myrouters
    			 ?.group=myrouters,boise

This will limit the results returned to those in a specific group or groups.

- ← Home
- Filtering
- Sorting →