Merge "placement: Make API history doc more consistent"
This commit is contained in:
Zuul
Gerrit Code Review
commit
9cf5d6bf98
@ -1,75 +1,100 @@
|
||||
REST API Version History
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This documents the changes made to the REST API with every
|
||||
microversion change. The description for each version should be a
|
||||
verbose one which has enough information to be suitable for use in
|
||||
user documentation.
|
||||
This documents the changes made to the REST API with every microversion change.
|
||||
The description for each version should be a verbose one which has enough
|
||||
information to be suitable for use in user documentation.
|
||||
|
||||
1.0 (Maximum in Newton)
|
||||
-----------------------
|
||||
.. _1.0 (Maximum in Newton):
|
||||
|
||||
1.0 Initial Version (Maximum in Newton)
|
||||
---------------------------------------
|
||||
|
||||
.. versionadded:: Newton
|
||||
|
||||
This is the initial version of the placement REST API that was released in
|
||||
Nova 14.0.0 (Newton). This contains the following routes:
|
||||
|
||||
* /resource_providers
|
||||
* /resource_providers/allocations
|
||||
* /resource_providers/inventories
|
||||
* /resource_providers/usages
|
||||
* /allocations
|
||||
* ``/resource_providers``
|
||||
* ``/resource_providers/allocations``
|
||||
* ``/resource_providers/inventories``
|
||||
* ``/resource_providers/usages``
|
||||
* ``/allocations``
|
||||
|
||||
1.1 Resource provider aggregates
|
||||
--------------------------------
|
||||
|
||||
The 1.1 version adds support for associating aggregates with
|
||||
resource providers with ``GET`` and ``PUT`` methods on one new
|
||||
route:
|
||||
.. versionadded:: Ocata
|
||||
|
||||
* /resource_providers/{uuid}/aggregates
|
||||
The 1.1 version adds support for associating aggregates with resource
|
||||
providers.
|
||||
|
||||
1.2 Custom resource classes
|
||||
---------------------------
|
||||
The following new operations are added:
|
||||
|
||||
``GET /resource_providers/{uuid}/aggregates``
|
||||
Return all aggregates associated with a resource provider
|
||||
|
||||
``PUT /resource_providers/{uuid}/aggregates``
|
||||
Update the aggregates associated with a resource provider
|
||||
|
||||
1.2 Add custom resource classes
|
||||
-------------------------------
|
||||
|
||||
.. versionadded:: Ocata
|
||||
|
||||
Placement API version 1.2 adds basic operations allowing an admin to create,
|
||||
list and delete custom resource classes.
|
||||
|
||||
The following new routes are added:
|
||||
|
||||
* GET /resource_classes: return all resource classes
|
||||
* POST /resource_classes: create a new custom resource class
|
||||
* PUT /resource_classes/{name}: update name of custom resource class
|
||||
* DELETE /resource_classes/{name}: deletes a custom resource class
|
||||
* GET /resource_classes/{name}: get a single resource class
|
||||
``GET /resource_classes``
|
||||
Return all resource classes
|
||||
|
||||
Custom resource classes must begin with the prefix "CUSTOM\_" and contain only
|
||||
the letters A through Z, the numbers 0 through 9 and the underscore "\_"
|
||||
``POST /resource_classes``
|
||||
Create a new custom resource class
|
||||
|
||||
``PUT /resource_classes/{name}``
|
||||
Update the name of a custom resource class
|
||||
|
||||
``DELETE /resource_classes/{name}``
|
||||
Delete a custom resource class
|
||||
|
||||
``GET /resource_classes/{name}``
|
||||
Get a single resource class
|
||||
|
||||
Custom resource classes must begin with the prefix ``CUSTOM_`` and contain only
|
||||
the letters A through Z, the numbers 0 through 9 and the underscore ``_``
|
||||
character.
|
||||
|
||||
1.3 member_of query parameter
|
||||
-----------------------------
|
||||
|
||||
Version 1.3 adds support for listing resource providers that are members of
|
||||
any of the list of aggregates provided using a ``member_of`` query parameter:
|
||||
.. versionadded:: Ocata
|
||||
|
||||
* /resource_providers?member_of=in:{agg1_uuid},{agg2_uuid},{agg3_uuid}
|
||||
Version 1.3 adds support for listing resource providers that are members of any
|
||||
of the list of aggregates provided using a ``member_of`` query parameter::
|
||||
|
||||
?member_of=in:{agg1_uuid},{agg2_uuid},{agg3_uuid}
|
||||
|
||||
1.4 Filter resource providers by requested resource capacity (Maximum in Ocata)
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Ocata
|
||||
|
||||
The 1.4 version adds support for querying resource providers that have the
|
||||
ability to serve a requested set of resources. A new "resources" query string
|
||||
parameter is now accepted to the `GET /resource_providers` API call. This
|
||||
parameter is now accepted to the ``GET /resource_providers`` API call. This
|
||||
parameter indicates the requested amounts of various resources that a provider
|
||||
must have the capacity to serve. The "resources" query string parameter takes
|
||||
the form:
|
||||
the form::
|
||||
|
||||
``?resources=$RESOURCE_CLASS_NAME:$AMOUNT,$RESOURCE_CLASS_NAME:$AMOUNT``
|
||||
?resources=$RESOURCE_CLASS_NAME:$AMOUNT,$RESOURCE_CLASS_NAME:$AMOUNT
|
||||
|
||||
For instance, if the user wishes to see resource providers that can service a
|
||||
request for 2 vCPUs, 1024 MB of RAM and 50 GB of disk space, the user can issue
|
||||
a request to:
|
||||
a request to::
|
||||
|
||||
`GET /resource_providers?resources=VCPU:2,MEMORY_MB:1024,DISK_GB:50`
|
||||
GET /resource_providers?resources=VCPU:2,MEMORY_MB:1024,DISK_GB:50
|
||||
|
||||
If the resource class does not exist, then it will return a HTTP 400.
|
||||
|
||||
@ -85,40 +110,58 @@ If the resource class does not exist, then it will return a HTTP 400.
|
||||
1.5 DELETE all inventory for a resource provider
|
||||
------------------------------------------------
|
||||
|
||||
.. versionadded:: Pike
|
||||
|
||||
Placement API version 1.5 adds DELETE method for deleting all inventory for a
|
||||
resource provider. The following new method is supported:
|
||||
|
||||
* DELETE /resource_providers/{uuid}/inventories
|
||||
``DELETE /resource_providers/{uuid}/inventories``
|
||||
|
||||
Delete all inventories for a given resource provider
|
||||
|
||||
1.6 Traits API
|
||||
--------------
|
||||
|
||||
.. versionadded:: Pike
|
||||
|
||||
The 1.6 version adds basic operations allowing an admin to create, list, and
|
||||
delete custom traits, also adds basic operations allowing an admin to attach
|
||||
traits to a resource provider.
|
||||
|
||||
The following new routes are added:
|
||||
|
||||
* GET /traits: Returns all resource classes.
|
||||
* PUT /traits/{name}: To insert a single custom trait.
|
||||
* GET /traits/{name}: To check if a trait name exists.
|
||||
* DELETE /traits/{name}: To delete the specified trait.
|
||||
* GET /resource_providers/{uuid}/traits: a list of traits associated
|
||||
with a specific resource provider
|
||||
* PUT /resource_providers/{uuid}/traits: Set all the traits for a
|
||||
specific resource provider
|
||||
* DELETE /resource_providers/{uuid}/traits: Remove any existing trait
|
||||
associations for a specific resource provider
|
||||
``GET /traits``
|
||||
Return all resource classes.
|
||||
|
||||
Custom traits must begin with the prefix "CUSTOM\_" and contain only
|
||||
the letters A through Z, the numbers 0 through 9 and the underscore "\_"
|
||||
``PUT /traits/{name}``
|
||||
Insert a single custom trait.
|
||||
|
||||
``GET /traits/{name}``
|
||||
Check if a trait name exists.
|
||||
|
||||
``DELETE /traits/{name}``
|
||||
Delete the specified trait.
|
||||
|
||||
``GET /resource_providers/{uuid}/traits``
|
||||
Return all traits associated with a specific resource provider.
|
||||
|
||||
``PUT /resource_providers/{uuid}/traits``
|
||||
Update all traits for a specific resource provider.
|
||||
|
||||
``DELETE /resource_providers/{uuid}/traits``
|
||||
Remove any existing trait associations for a specific resource provider
|
||||
|
||||
Custom traits must begin with the prefix ``CUSTOM_`` and contain only the
|
||||
letters A through Z, the numbers 0 through 9 and the underscore ``_``
|
||||
character.
|
||||
|
||||
1.7 Idempotent PUT /resource_classes/{name}
|
||||
-------------------------------------------
|
||||
|
||||
The 1.7 version changes handling of `PUT /resource_classes/{name}` to be a
|
||||
create or verification of the resource class with `{name}`. If the resource
|
||||
.. versionadded:: Pike
|
||||
|
||||
The 1.7 version changes handling of ``PUT /resource_classes/{name}`` to be a
|
||||
create or verification of the resource class with ``{name}``. If the resource
|
||||
class is a custom resource class and does not already exist it will be created
|
||||
and a ``201`` response code returned. If the class already exists the response
|
||||
code will be ``204``. This makes it possible to check or create a resource
|
||||
@ -127,27 +170,31 @@ class in one request.
|
||||
1.8 Require placement 'project_id', 'user_id' in PUT /allocations
|
||||
-----------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Pike
|
||||
|
||||
The 1.8 version adds ``project_id`` and ``user_id`` required request parameters
|
||||
to ``PUT /allocations``.
|
||||
|
||||
1.9 Add GET /usages
|
||||
--------------------
|
||||
|
||||
.. versionadded:: Pike
|
||||
|
||||
The 1.9 version adds usages that can be queried by a project or project/user.
|
||||
|
||||
The following new routes are added:
|
||||
|
||||
``GET /usages?project_id=<project_id>``
|
||||
|
||||
Returns all usages for a given project.
|
||||
Return all usages for a given project.
|
||||
|
||||
``GET /usages?project_id=<project_id>&user_id=<user_id>``
|
||||
|
||||
Returns all usages for a given project and user.
|
||||
Return all usages for a given project and user.
|
||||
|
||||
1.10 Allocation candidates (Maximum in Pike)
|
||||
--------------------------------------------
|
||||
|
||||
.. versionadded:: Pike
|
||||
|
||||
The 1.10 version brings a new REST resource endpoint for getting a list of
|
||||
allocation candidates. Allocation candidates are collections of possible
|
||||
allocations against resource providers that can satisfy a particular request
|
||||
@ -156,6 +203,8 @@ for resources.
|
||||
1.11 Add 'allocations' link to the ``GET /resource_providers`` response
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
The ``/resource_providers/{rp_uuid}/allocations`` endpoint has been available
|
||||
since version 1.0, but was not listed in the ``links`` section of the
|
||||
``GET /resource_providers`` response. The link is included as of version 1.11.
|
||||
@ -163,25 +212,31 @@ since version 1.0, but was not listed in the ``links`` section of the
|
||||
1.12 PUT dict format to /allocations/{consumer_uuid}
|
||||
----------------------------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
In version 1.12 the request body of a ``PUT /allocations/{consumer_uuid}``
|
||||
is expected to have an `object` for the ``allocations`` property, not as
|
||||
`array` as with earlier microversions. This puts the request body more in
|
||||
is expected to have an ``object`` for the ``allocations`` property, not as
|
||||
``array`` as with earlier microversions. This puts the request body more in
|
||||
alignment with the structure of the ``GET /allocations/{consumer_uuid}``
|
||||
response body. Because the `PUT` request requires `user_id` and
|
||||
`project_id` in the request body, these fields are added to the `GET`
|
||||
response body. Because the ``PUT`` request requires ``user_id`` and
|
||||
``project_id`` in the request body, these fields are added to the ``GET``
|
||||
response. In addition, the response body for ``GET /allocation_candidates``
|
||||
is updated so the allocations in the ``alocation_requests`` object work
|
||||
with the new `PUT` format.
|
||||
with the new ``PUT`` format.
|
||||
|
||||
1.13 POST multiple allocations to /allocations
|
||||
----------------------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
Version 1.13 gives the ability to set or clear allocations for more than
|
||||
one consumer uuid with a request to ``POST /allocations``.
|
||||
one consumer UUID with a request to ``POST /allocations``.
|
||||
|
||||
1.14 Add nested resource providers
|
||||
----------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
The 1.14 version introduces the concept of nested resource providers. The
|
||||
resource provider resource now contains two new attributes:
|
||||
|
||||
@ -201,6 +256,8 @@ provider matching ``<UUID>`` to be returned.
|
||||
1.15 Add 'last-modified' and 'cache-control' headers
|
||||
----------------------------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
Throughout the API, 'last-modified' headers have been added to GET responses
|
||||
and those PUT and POST responses that have bodies. The value is either the
|
||||
actual last modified time of the most recently modified associated database
|
||||
@ -211,25 +268,31 @@ header has been added to prevent inadvertent caching of resources.
|
||||
1.16 Limit allocation candidates
|
||||
--------------------------------
|
||||
|
||||
.. versionadded:: Queens
|
||||
|
||||
Add support for a ``limit`` query parameter when making a
|
||||
``GET /allocation_candidates`` request. The parameter accepts an integer
|
||||
value, `N`, which limits the maximum number of candidates returned.
|
||||
value, ``N``, which limits the maximum number of candidates returned.
|
||||
|
||||
1.17 Add 'required' parameter to the allocation candidates (Maximum in Queens)
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
Add the `required` parameter to the `GET /allocation_candidates` API. It
|
||||
accepts a list of traits separated by `,`. The provider summary in the response
|
||||
will include the attached traits also.
|
||||
.. versionadded:: Queens
|
||||
|
||||
Add the ``required`` parameter to the ``GET /allocation_candidates`` API. It
|
||||
accepts a list of traits separated by ``,``. The provider summary in the
|
||||
response will include the attached traits also.
|
||||
|
||||
1.18 Support ?required=<traits> queryparam on GET /resource_providers
|
||||
---------------------------------------------------------------------
|
||||
|
||||
Add support for the `required` query parameter to the `GET /resource_providers`
|
||||
API. It accepts a comma-separated list of string trait names. When specified,
|
||||
the API results will be filtered to include only resource providers marked with
|
||||
all the specified traits. This is in addition to (logical AND) any filtering
|
||||
based on other query parameters.
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Add support for the ``required`` query parameter to the ``GET
|
||||
/resource_providers`` API. It accepts a comma-separated list of string trait
|
||||
names. When specified, the API results will be filtered to include only
|
||||
resource providers marked with all the specified traits. This is in addition to
|
||||
(logical AND) any filtering based on other query parameters.
|
||||
|
||||
Trait names which are empty, do not exist, or are otherwise invalid will result
|
||||
in a 400 error.
|
||||
@ -237,27 +300,33 @@ in a 400 error.
|
||||
1.19 Include generation and conflict detection in provider aggregates APIs
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
Enhance the payloads for the `GET /resource_providers/{uuid}/aggregates`
|
||||
response and the `PUT /resource_providers/{uuid}/aggregates` request and
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Enhance the payloads for the ``GET /resource_providers/{uuid}/aggregates``
|
||||
response and the ``PUT /resource_providers/{uuid}/aggregates`` request and
|
||||
response to be identical, and to include the ``resource_provider_generation``.
|
||||
As with other generation-aware APIs, if the ``resource_provider_generation``
|
||||
specified in the `PUT` request does not match the generation known by the
|
||||
specified in the ``PUT`` request does not match the generation known by the
|
||||
server, a 409 Conflict error is returned.
|
||||
|
||||
1.20 Return 200 with provider payload from POST /resource_providers
|
||||
-------------------------------------------------------------------
|
||||
|
||||
The `POST /resource_providers` API, on success, returns 200 with a payload
|
||||
.. versionadded:: Rocky
|
||||
|
||||
The ``POST /resource_providers`` API, on success, returns 200 with a payload
|
||||
representing the newly-created resource provider, in the same format as the
|
||||
corresponding `GET /resource_providers/{uuid}` call. This is to allow the
|
||||
corresponding ``GET /resource_providers/{uuid}`` call. This is to allow the
|
||||
caller to glean automatically-set fields, such as UUID and generation, without
|
||||
a subsequent GET.
|
||||
|
||||
1.21 Support ?member_of=<aggregates> queryparam on GET /allocation_candidates
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
Add support for the `member_of` query parameter to the `GET
|
||||
/allocation_candidates` API. It accepts a comma-separated list of UUIDs for
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Add support for the ``member_of`` query parameter to the ``GET
|
||||
/allocation_candidates`` API. It accepts a comma-separated list of UUIDs for
|
||||
aggregates. Note that if more than one aggregate UUID is passed, the
|
||||
comma-separated list must be prefixed with the "in:" operator. If this
|
||||
parameter is provided, the only resource providers returned will be those in
|
||||
@ -266,6 +335,8 @@ one of the specified aggregates that meet the other parts of the request.
|
||||
1.22 Support forbidden traits on resource providers and allocations candidates
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Add support for expressing traits which are forbidden when filtering
|
||||
``GET /resource_providers`` or ``GET /allocation_candidates``. A forbidden
|
||||
trait is a properly formatted trait in the existing ``required`` parameter,
|
||||
@ -275,6 +346,8 @@ results not include any resource providers that provide solid state disk.
|
||||
1.23 Include code attribute in JSON error responses
|
||||
---------------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
JSON formatted error responses gain a new attribute, ``code``, with a value
|
||||
that identifies the type of this error. This can be used to distinguish errors
|
||||
that are different but use the same HTTP status code. Any error response which
|
||||
@ -284,6 +357,8 @@ does not specifically define a code will have the code
|
||||
1.24 Support multiple ?member_of queryparams
|
||||
--------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Add support for specifying multiple ``member_of`` query parameters to the ``GET
|
||||
/resource_providers`` API. When multiple ``member_of`` query parameters are
|
||||
found, they are AND'd together in the final query. For example, issuing a
|
||||
@ -296,6 +371,8 @@ associated with *any of* (agg1, agg2).
|
||||
1.25 Granular resource requests to ``GET /allocation_candidates``
|
||||
-----------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
``GET /allocation_candidates`` is enhanced to accept numbered groupings of
|
||||
resource, required/forbidden trait, and aggregate association requests. A
|
||||
``resources`` query parameter key with a positive integer suffix (e.g.
|
||||
@ -327,12 +404,16 @@ non-sharing tree or associated via the specified aggregate(s).
|
||||
1.26 Allow inventories to have reserved value equal to total
|
||||
------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Starting with this version, it is allowed to set the reserved value of the
|
||||
resource provider inventory to be equal to total.
|
||||
|
||||
1.27 Include all resource class inventories in provider_summaries
|
||||
-----------------------------------------------------------------
|
||||
|
||||
.. versionadded:: Rocky
|
||||
|
||||
Include all resource class inventories in the ``provider_summaries`` field in
|
||||
response of the ``GET /allocation_candidates`` API even if the resource class
|
||||
is not in the requested resources.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user