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 |
Supported filter fields:
The RESTful v2 API currently
supports a variety of filterable fields for each resource type. Each release
adds support for additional filterable fields, targeting an ultimate goal of
filter support for all resource fields where feasible. If an unsupported field
is provided with the filter parameter, the API will respond with a 400
InvalidFilterField error and a list of supported filter
fields for that endpoint.
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")range fields, the value
provided when using the eq, ge,
gt, le, and lt
operators must be a range. The eq operator accepts ranges
in the form of a CIDR length (eq("/16")), address and CIDR
length (eq("192.168.0.0/16")), or address range
(eq("192.168.0.0-192.168.0.255"). The
eq operator will return resources that match the
provided range value exactly, therefore filtering by CIDR
length only will return all resources matching the CIDR length, while the
inclusion of an address will return only resources matching both
address and length. The following example will return all blocks with a CIDR
length of
24:GET http://{Address_Manager_IP}/api/v2/blocks?filter=range:eq("/24")ge, gt, le, and
lt operators accept either CIDR length
(gt("/16")) or address and CIDR length
(gt("192.168.0.0/16")) for the range
value, and will return results based on size comparison
of the CIDR length. If only a CIDR length is provided, both IPv4 and IPv6
resources that meet the size comparison criteria will be returned. If an
address and CIDR length is provided, the resources returned will match the
address protocol type (however unlike eq, resources
returned are not limited to the exact address). The following example will
return all IPv4 Blocks that are greater than or equal to CIDR length
16:GET http://{Address_Manager_IP}/api/v2/blocks?filter=range:ge("192.168.0.0/16")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')Retrieve all Blocks with a configuration.name equal to
'config-2' or 'config-3'
GET http://{Address_Manager_IP}/api/v2/blocks?filter=configuration.name:in('config-2', 'config-3')Retrieve all Addresses in a Network with a state equal to
'RESERVED' or 'DHCP_RESERVED'
GET http://{Address_Manager_IP}/api/v2/networks/{Network_ID}/addresses?filter=state:in('RESERVED', 'DHCP_RESERVED')Retrieve all Networks that are immediate children of a Block
GET http://{Address_Manager_IP}/api/v2/blocks/{Block_ID}/networksRetrieve all Networks that are children of a '10.0.0.0/8' Block within Configuration 'config0', including children of sub-blocks.
GET http://{Address_Manager_IP}/api/v2/networks?filter=configuration.name:'config0' and range:startsWith('10.')