REST API Filtering¶
The objects returned by an API list endpoint can be filtered by attaching one or more query parameters to the request URL. For example,
GET /api/dcim/locations/?status=active will return only locations with a status of "active."
Multiple parameters can be joined to further narrow results. For example,
GET /api/dcim/locations/?status=active&parent=europe&location_type=country will return only active "country" type locations in Europe.
Generally, passing multiple values for a single parameter will result in a logical OR operation. For example,
GET /api/dcim/locations/?parent=north-america&parent=south-america&location_type=country will return "country" type locations in North America or South America. However, a logical AND operation will be used in instances where a field may have multiple values, such as tags. For example,
GET /api/dcim/locations/?tag=foo&tag=bar will return only locations which have both the "foo" and "bar" tags applied.
Changed in version 1.4.0
If STRICT_FILTERING is True (its default value), unrecognized filter parameters now result in a 400 Bad Request response instead of being silently ignored.
Filtering by Choice Field¶
Some models have fields which are limited to specific choices, such as the
type field on the Interface model. To find all available choices for this field, make an authenticated
OPTIONS request to the model's list endpoint, and use
jq to extract the relevant parameters:
The above works only if the API token used to authenticate the request has permission to make a
POST request to this endpoint.
Filtering by Custom Field¶
To filter results by a custom field value, prepend
cf_ to the custom field key. For example, the following query will return only locations where a custom field with key
foo is equal to 123:
For custom field filters, due to historical details of implementation, only a single filter value can be specified when matching a given field. In other words, in the above example, you could not add
&cf_foo=456 to the query in order to get all locations where custom field
foo is 123 or 456; instead you would need to run two separate queries. This restriction does not apply to custom field filters using lookup expressions (next section) and will likely be changed in a future major version of Nautobot.
Custom fields can be mixed with built-in fields to further narrow results. When creating a custom string field, the type of filtering selected (loose versus exact) determines whether partial or full matching is used.
Added in version 1.4.0
Custom fields can use the lookup expressions listed in the next section by prepending
cf_ to the custom field
name (not the
slug) followed by the required lookup type (see below).
Changed in version 2.0.0
Custom field filters are now based on the custom field
Certain model fields (including, in Nautobot 1.4.0 and later, custom fields of type
date) also support filtering using additional lookup expressions. This allows
for negation and other context-specific filtering.
These lookup expressions can be applied by adding a suffix to the desired field's name, e.g.
mac_address__n. In this case, the filter expression is for negation and it is separated by two underscores. Below are the lookup expressions that are supported across different field types.
Numeric-based fields (ASN, VLAN ID, etc.) support these lookup expressions:
n- not equal to (negation)
lt- less than
lte- less than or equal
gt- greater than
gte- greater than or equal
String-based (char) fields (Name, Address, etc.) support these lookup expressions:
n- not equal to (negation)
ic- case-insensitive contains
nic- negated case-insensitive contains
isw- case-insensitive starts-with
nisw- negated case-insensitive starts-with
iew- case-insensitive ends-with
niew- negated case-insensitive ends-with
ie- case-insensitive exact match
nie- negated case-insensitive exact match
Added in version 1.3.0
re- case-sensitive regular expression match
nre- negated case-sensitive regular expression match
ire- case-insensitive regular expression match
nire- negated case-insensitive regular expression match
Foreign Keys & Other Fields¶
Certain other fields, namely foreign key relationships support just the negation
Network and Host Fields¶
There are Custom Lookups built for the
VarbinaryIPField field types. While
VarbinaryIPField is applied to fields for network, host, and broadcast, the below filters only apply to network and host. The design
makes an assumption that there is in fact a broadcast (of type
VarbinaryIPField) and prefix_length (of type
Integer) within the same
model. This assumption is used to understand the relevant scope of the network in question and is important to note when extending the
Nautobot core or plugin data model.
exact- An exact match of an IP or network address, e.g.
iexact- An exact match of an IP or network address, e.g.
startswith- Determine if IP or network starts with the value provided, e.g.
istartswith- Determine if IP or network starts with the value provided, e.g.
endswith- Determine if IP or network ends with the value provided, e.g.
iendswith- Determine if IP or network ends with the value provided, e.g.
regex- Determine if IP or network matches the pattern provided, e.g.
iregex- Determine if IP or network matches the pattern provided, e.g.
net_contained- Given a network, determine which networks are contained within the provided e.g.
network__net_contained="192.0.0.0/8"would include 192.168.0.0/24 in the result
net_contained_or_equal- Given a network, determine which networks are contained or is within the provided e.g.
network__net_contained_or_equal="192.0.0.0/8"would include 192.168.0.0/24 and 192.0.0.0/8 in the result
net_contains- Given a network, determine which networks contain the provided network e.g.
network__net_contains="192.168.0.0/16"would include 192.0.0.0/8 in the result
net_contains_or_equals- Given a network, determine which networks contain or is the provided network e.g.
network__net_contains="192.168.0.0/16"would include 192.0.0.0/8 and 192.168.0.0/16 in the result
net_equals- Given a network, determine which which networks are an exact match. e.g.
network__net_equals="192.168.0.0/16"would include only 192.168.0.0/16 in the result
net_host- Determine which networks are parent of the provided IP, e.g.
host__net_host="10.0.0.1"would include 10.0.0.1/32 and 10.0.0.0/24 in the result
net_host_contained- Given a network, select IPs whose host address (regardless of its subnet mask) falls within that network , e.g.
host__net_host_contained="10.0.0.0/24"would include hosts 10.0.0.1/8 and 10.0.0.254/32 in the result
net_in- Given a list of networks, select addresses (regardless of their subnet masks) within those networks, e.g.
host__net_in=["10.0.0.0/24", "2001:db8::/64"]would include hosts 10.0.0.1/16 and 2001:db8::1/65 in the result
family- Given an IP address family of 4 or 6, provide hosts or networks that are that IP version type, e.g.
host__family=6would include 2001:db8::1 in the result
Note: The fields denoted with
**are only supported in the MySQL dialect (and not Postgresql) at the current time.