diff --git a/api-ref/source/allocation_candidates.inc b/api-ref/source/allocation_candidates.inc index c0cd61b12..53a4afb03 100644 --- a/api-ref/source/allocation_candidates.inc +++ b/api-ref/source/allocation_candidates.inc @@ -34,11 +34,11 @@ Request - resources: resources_query_ac - required: required_traits_unnumbered - - member_of: member_of_1_21 + - member_of: allocation_candidates_member_of - in_tree: allocation_candidates_in_tree - resourcesN: resources_query_granular - requiredN: required_traits_granular - - member_ofN: member_of_granular + - member_ofN: allocation_candidates_member_of_granular - in_treeN: allocation_candidates_in_tree_granular - group_policy: allocation_candidates_group_policy - limit: allocation_candidates_limit diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index d90666dd5..6664de06b 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -81,58 +81,7 @@ allocation_candidates_limit: description: > A positive integer used to limit the maximum number of allocation candidates returned in the response. -member_of: - type: string - in: query - required: false - description: > - A string representing an aggregate uuid; or the prefix ``in:`` followed by - a comma-separated list of strings representing aggregate uuids. The - returned resource providers must directly be associated with at least one - of the aggregates identified by uuid:: - - member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa - member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa - - **Starting from microversion 1.24** specifying multiple ``member_of`` query - string parameters is possible. Multiple ``member_of`` parameters will - result in filtering providers that are associated with aggregates listed in - all of the ``member_of`` query string values. For example, to get the - providers that are associated with aggregate A as well as associated with - any of aggregates B or C, the user could issue the following query:: - - member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID - - **Starting from microversion 1.32** specifying forbidden aggregates is - supported in the ``member_of`` query string parameter. Forbidden aggregates - are prefixed with a ``!``. This negative expression can also be used in - multiple ``member_of`` parameters:: - - member_of=AGGA_UUID&member_of=!AGGB_UUID - - would translate logically to "Candidate resource providers must be in AGGA - and *not* in AGGB." - - We do NOT support ``!`` on the values within ``in:``, but we support - ``!in:``. Both of the following two example queries return candidate - resource providers that are NOT in AGGA, AGGB, or AGGC:: - - member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID - member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID - - We do not check if the same aggregate uuid is in both positive and negative - expression to return 400 BadRequest. We still return 200 for such cases. - For example:: - - member_of=AGGA_UUID&member_of=!AGGA_UUID - - would return an empty list for ``resource_providers``, while:: - - member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID - - would return resource providers that are NOT in AGGA but in AGGB. - min_version: 1.3 -member_of_1_21: +allocation_candidates_member_of: type: string in: query required: false @@ -185,7 +134,7 @@ member_of_1_21: would return resource providers that are NOT in AGGA but in AGGB. min_version: 1.21 -member_of_granular: +allocation_candidates_member_of_granular: type: string in: query required: false @@ -257,6 +206,57 @@ required_traits_unnumbered: associated via aggregate. **Starting from microversion 1.22** traits which are forbidden from any resource provider may be expressed by prefixing a trait with a ``!``. +resource_provider_member_of: + type: string + in: query + required: false + description: > + A string representing an aggregate uuid; or the prefix ``in:`` followed by + a comma-separated list of strings representing aggregate uuids. The + returned resource providers must directly be associated with at least one + of the aggregates identified by uuid:: + + member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa + member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa + + **Starting from microversion 1.24** specifying multiple ``member_of`` query + string parameters is possible. Multiple ``member_of`` parameters will + result in filtering providers that are associated with aggregates listed in + all of the ``member_of`` query string values. For example, to get the + providers that are associated with aggregate A as well as associated with + any of aggregates B or C, the user could issue the following query:: + + member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID + + **Starting from microversion 1.32** specifying forbidden aggregates is + supported in the ``member_of`` query string parameter. Forbidden aggregates + are prefixed with a ``!``. This negative expression can also be used in + multiple ``member_of`` parameters:: + + member_of=AGGA_UUID&member_of=!AGGB_UUID + + would translate logically to "Candidate resource providers must be in AGGA + and *not* in AGGB." + + We do NOT support ``!`` on the values within ``in:``, but we support + ``!in:``. Both of the following two example queries return candidate + resource providers that are NOT in AGGA, AGGB, or AGGC:: + + member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID + member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID + + We do not check if the same aggregate uuid is in both positive and negative + expression to return 400 BadRequest. We still return 200 for such cases. + For example:: + + member_of=AGGA_UUID&member_of=!AGGA_UUID + + would return an empty list for ``resource_providers``, while:: + + member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID + + would return resource providers that are NOT in AGGA but in AGGB. + min_version: 1.3 resource_provider_name_query: type: string in: query diff --git a/api-ref/source/resource_providers.inc b/api-ref/source/resource_providers.inc index 8dfaad7b9..b147fd75f 100644 --- a/api-ref/source/resource_providers.inc +++ b/api-ref/source/resource_providers.inc @@ -32,7 +32,7 @@ of all filters are merged with a boolean `AND`. - name: resource_provider_name_query - uuid: resource_provider_uuid_query - - member_of: member_of + - member_of: resource_provider_member_of - resources: resources_query_1_4 - in_tree: resource_provider_tree_query - required: resource_provider_required_query