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.
- Retrieve only ports in a specific administrative state
- Retrieve only ports in a specific operational state
- Retrieve only ports with an interface plugged
- Retrieve only networks with operational ports
- Retrieve only networks with interfaces plugged
- 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