Filter - BlueCat Integrity - 9.5.0

Address Manager RESTful v2 API Guide

Locale
English
Product name
BlueCat Integrity
Version
9.5.0

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.

Note: 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 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")
The 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")
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')

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}/networks

Retrieve 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.')