The RESTful v2 API supports results filtering using the filter
query parameter.
The value supplied to the filter
parameter is a list of field predicates using the API's filter
grammar:
filter=<field>:operator(value)
For example,
the following filter
string will instruct the API to filter
User resources with names containing the string
‘bc’:
GET http://{Address_Manager_IP}/api/v2/users?filter=name:contains('bc')
In
this example contains()
is a filter
operator.
The list of supported operators is specific to the resource field.
Supported filter operators:
Operator |
Description |
Field Types |
eq | Equals | numbers, strings, addresses, dates, enums, booleans, ranges |
ne | Not equals | numbers, strings, addresses, enums, booleans |
ge | Greater than equals | numbers, dates, addresses, ranges |
gt | Greater than | numbers, dates, addresses, ranges |
le | Less than equals | numbers, dates, addresses, ranges |
lt | Less than | numbers, dates, addresses, ranges |
contains | Contains | strings, ranges |
startsWith | Starts with | strings, ranges |
endsWith | Ends with | strings |
in | Match a list of values | numbers, strings, enums, booleans, addresses |
address
and range
fields are strings
with special handling to allow comparison. When filtering by
address
fields, the value
provided
must also be an address. The following example retrieves Addresses greater
than 192.168.0.10 for a specified
Network:GET http://{Address_Manager_IP}/api/v2/networks/{collectionId}/addresses?filter=address:gt("192.168.0.10")
When
filtering by range
fields, the value
provided when using the eq
, ge
,
gt
, le
, and lt
operators must be a range. The eq
operator will return
resources with range
fields that match the range
value
exactly (address and CIDR), while the
ge
, gt
, le
, and
lt
operators will return results based on size
comparison of the CIDR length of the range value
. The
following example will return all IPv4 Blocks that are greater than or equal
to CIDR length
24:GET http://{Address_Manager_IP}/api/v2/blocks?filter=range:ge("192.168.0.0/24")
The contains
and startWith
operators are
also supported for range
fields, by providing an address
for the value
. The following example will return all IPv4
Networks that contain the address
10.0.0.5:GET http://{Address_Manager_IP}/api/v2/networks?filter=range:contains("10.0.0.5")
Combination of filter predicates
Filter predicates can be
combined to form more complex filters using the and
and
or
operators:
Retrieve Transactions with a
creationDateTime
greater than '2022-01-10T14:14:45Z'
and less than '2022-01-20T14:14:45Z'
GET http://{Address_Manager_IP}/api/v2/transactions?filter=creationDateTime:ge('2022-01-10T14:14:45Z') and creationDateTime:le('2022-01-20T14:14:45Z')
Additional examples:
Retrieve all Users with a
name
equal to 'admin1' (implied eq)
GET http://{Address_Manager_IP}/api/v2/users?filter=name:'admin1'
Retrieve all Addresses greater than or equal to '192.168.0.0' and less than or equal to '192.168.0.255'
GET http://{Address_Manager_IP}/api/v2/addresses?filter=address:ge('192.168.0.0') and address:le('192.168.0.255')
Retrieve all Networks with a value of true
for the
pingBeforeAssignEnabled
field.
GET http://{Address_Manager_IP}/api/v2/networks?filter=pingBeforeAssignEnabled:eq(true)
Retrieve all Blocks with a name
that contains 'UK' or
'FR'
GET http://{Address_Manager_IP}/api/v2/blocks?filter=name:contains('UK') or name:contains('FR')