Difference between revisions of "Quantum-api-filters"
| Line 24: | Line 24: | ||
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. | 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 [http://docs.openstack.org/api/openstack-compute/1.1/content/List_Servers-d1e2078.html List Servers] operation. | + | ''For more information on the use of filters in the Openstack API, please look at the documentation for the [http://docs.openstack.org/api/openstack-compute/1.1/content/List_Servers-d1e2078.html 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. | 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: | User should be able to specify filters using: | ||
* '''Attributes of the resource being listed''' | * '''Attributes of the resource being listed''' | ||
| − | + | ** Example: ''Retrieve only networks whose name is "private" for tenant XXX'' | |
| − | + | ** <code><nowiki>GET <quantum_endpoint>/tenants/XXX/networks?name=private</nowiki></code> | |
| − | |||
* '''Predicates made available by the resource being listed''' | * '''Predicates made available by the resource being listed''' | ||
| − | + | ** Example: ''Retrieve only ports operationally UP for networks AAA of tenant XXX'' | |
| − | + | ** <code><nowiki>GET <quantum_endpoint>/tenants/XXX/networks/AAA/port-op-status=UP</nowiki></code> | |
== Implementation == | == Implementation == | ||
Revision as of 16:00, 13 December 2011
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 operationally UP for networks AAA of tenant XXX
-
GET <quantum_endpoint>/tenants/XXX/networks/AAA/port-op-status=UP
