Quantum-api-filters

Filters for Quantum API

Summary

The goal of this blueprint is to improve the Quantum API by providing a mechanism allowing users to specify filters to be applied on responses. Such mechanism would be particularly useful for "list" API operations, which might return large amounts of data.

Typical Use Cases

We list in this section situations in which API filters might be employed by users of the Quantum API. Please feel free to add your own use cases here.

1. Retrieve only ports in a specific administrative state
2. Retrieve only ports in a specific operational state
3. Retrieve only ports with an interface plugged
4. Retrieve only networks with operational ports
5. Retrieve only networks with interfaces plugged
6. Retrieve only networks matching specific names or name patterns

Specification

Users will be able to specify filters using the request URI's query string. Although filters could be be specified also in appropriate request header and/or in the request body, the choice of the query string is to be preferred for consistency with the Openstack API.

For more information on the use of filters in the Openstack API, please look at the documentation for the List Servers operation.

Filters are in general resource-specific; in Quantum terms, this means that the set of filters which apply to network resource do not necessarily apply to port resource as well. User should be able to specify filters using:

• Attributes of the resource being listed
  • Example: Retrieve only networks whose name is "private" for tenant XXX
  • GET <quantum_endpoint>/tenants/XXX/networks?name=private
• Predicates made available by the resource being listed
  • Example: Retrieve only ports with an interface plugged in it for network AAA of tenant XXX
  • GET <quantum_endpoint>/tenants/XXX/networks/AAA/ports/has-interface=True

Several filters can be combined on the same request URI, as in the following example, which retrieves ports which are administratively UP but operationally DOWN: GET <quantum_endpoint>/tenants/XXX/networks/AAA/ports/state=UP&op-status=DOWN

For the first prototype of this feature, to be included in Quantum API v1.1, clients will be able to perform filtering using the following attributes and filters:

Resource	Attribute/Predicate	Value
Network	name	Name of the network
	op-status	Operational status
	has-operational-port	False
	has-active-port	False
	has-interface	False
	with-interface	Interface Identifier
Port	state	DOWN
	op-status	Operational status
	has-interface	False
with-interface	Interface Identifier

NOTE: Labels used for predicates are purely hypothetical at this stage