nova/placement-api-ref/source/traits.inc
Takashi NATSUME de6e2b9948 [placement] Move body examples to an isolated directory
JSON body examples of Placement API reference
are in the same directroy where *.inc files exist.

This patch moves JSON body examples to an isolated directory
in order to make it easier to maintain the API reference.

Change-Id: I8fd587100d22bd10dd4b2b2f1b25c5ecc7fc8537
2018-02-08 21:59:19 +00:00

136 lines
2.9 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:: ./samples/traits/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
--------
.. rest_parameters:: parameters.yaml
- Location: location
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.