[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

placement-api-ref/source/get-traits.json

@@ -0,0 +1,7 @@
+{
+    "traits": [
+        "CUSTOM_HW_FPGA_CLASS1",
+        "CUSTOM_HW_FPGA_CLASS2",
+        "CUSTOM_HW_FPGA_CLASS3"
+    ]
+}

placement-api-ref/source/index.rst

@@ -20,3 +20,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: inventories.inc
 .. include:: inventory.inc
 .. include:: aggregates.inc
+.. include:: traits.inc

placement-api-ref/source/parameters.yaml

@@ -11,6 +11,12 @@ resource_provider_uuid_path: &resource_provider_uuid_path
   required: true
   description: >
     The uuid of a resource provider.
+trait_name:
+  type: string
+  in: path
+  required: true
+  description: >
+    The name of a trait.
 
 # variables in query
 member_of:
@@ -41,6 +47,26 @@ resources_query:
     capacity to serve::
 
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
+trait_associated:
+  type: string
+  in: query
+  required: false
+  description: >
+     If this parameter has a true value, the returned traits will be
+     those that are associated with at least one resource provider.
+     Available values for the parameter are true and false.
+trait_name_query:
+  type: string
+  in: query
+  required: false
+  description: |
+    A string to filter traits. The following options are available:
+
+    `starts_with` operator filters the traits whose name begins with a
+    specific prefix, e.g. name=starts_with:CUSTOM,
+
+    `in` operator filters the traits whose name is in the specified list, e.g.
+    name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE.
 
 # variables in body
 aggregates:
@@ -166,6 +192,12 @@ total:
   required: true
   description: >
     The actual amount of the resource that the provider can accommodate.
+traits:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of traits.
 version_id:
   type: string
   in: body

placement-api-ref/source/traits.inc

@@ -0,0 +1,131 @@
+======
+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.