nova/placement-api-ref/source/traits.inc
Andrey Volkov 67028cb732 [placement] Add api-ref for traits
This provides simple documentation of the path, request and response
body parameters when listing, creating, updating and deleting traits.

Change-Id: If377b725e0910de2e1768666184a0212c8c9fdbc
2017-07-18 12:44:04 +03:00

132 lines
2.8 KiB
PHP

======
Traits
======
Traits are *qualitative* characteristics of resource providers.
The classic example for traits can be requesting disk from different
providers: a user may request 80GB of disk space for an instance
(quantitative), but may also expect that the disk be SSD instead of
spinning disk (qualitative). Traits provide a way to mark that a
storage provider is SSD or spinning.
.. note:: Traits API requests are availiable starting from version 1.6.
List traits
===========
Return a list of valid trait strings according to parameters specified.
.. rest_method:: GET /traits
Normal Response Codes: 200
Request
-------
Several query parameters are available to filter the returned list of
traits. If multiple different parameters are provided, the results
of all filters are merged with a boolean `AND`.
.. rest_parameters:: parameters.yaml
- name: trait_name_query
- associated: trait_associated
Response
--------
.. rest_parameters:: parameters.yaml
- traits: traits
Response Example
----------------
.. literalinclude:: get-traits.json
:language: javascript
Show traits
===========
Check if a trait name exists in this cloud.
.. rest_method:: GET /traits/{name}
Normal Response Codes: 204
Error response codes: itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- name: trait_name
Response
--------
No body content is returned on a successful GET.
Update traits
=============
Insert a new custom trait. If traits already exists 204 will be returned.
There are two kinds of traits: the standard traits and the custom traits.
The standard traits are interoperable across different Openstack cloud
deployments. The definition of standard traits comes from the `os-traits`
library. The standard traits are read-only in the placement API which means
that the user can't modify any standard traits through API.
The custom traits are used by admin users to manage the non-standard
qualitative information of resource providers.
.. rest_method:: PUT /traits/{name}
Normal Response Codes: 201, 204
Error response codes: badRequest(400)
* `400 BadRequest` if trait name is not prefixed with `CUSTOM_` prefix.
Request
-------
.. rest_parameters:: parameters.yaml
- name: trait_name
Response
--------
No body content is returned on a successful PUT.
Delete traits
=============
Delete the trait specified be `{name}`. Note that only custom traits can be
deleted.
.. rest_method:: DELETE /traits/{name}
Normal Response Codes: 204
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
* `400 BadRequest` if the name to delete is standard trait.
* `404 Not Found` if no such trait exists.
* `409 Conflict` if the name to delete has associations with any
ResourceProvider.
Request
-------
.. rest_parameters:: parameters.yaml
- name: trait_name
Response
--------
No body content is returned on a successful DELETE.