[placement] Add api-ref for RP traits

This provides simple documentation of the path, request and response
body parameters when managing the association between traits and
resource_providers.

Change-Id: I2ef25313db89a2fd58d11dc023d2d9755d0a86ed

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

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

placement-api-ref/source/index.rst

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

placement-api-ref/source/resource_provider_traits.inc

@@ -0,0 +1,115 @@
+========================
+Resource provider traits
+========================
+
+See `Traits`_ for a description.
+This group of API requests queries/edits the association between
+traits and resource providers.
+
+.. note:: Traits API requests are availiable starting from version 1.6.
+
+List resource provider traits
+=============================
+
+Return a list of traits for the resource provider identified by `{uuid}`.
+
+.. rest_method:: GET /resource_providers/{uuid}/traits
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - traits: traits
+  - resource_provider_generation: resource_provider_generation
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_provider-traits.json
+   :language: javascript
+
+Update resource provider traits
+===============================
+
+Associate traits with the resource provider identified by `{uuid}`.
+All the associated traits will be replaced by the traits specified in
+the request body.
+
+.. rest_method:: PUT /resource_providers/{uuid}/traits
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+* `400 Bad Request` if any of the specified traits are not valid. The valid
+  traits can be queried by `GET /traits`.
+* `409 Conflict` if the `resource_provider_generation` doesn't match with the
+  server side.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+  - traits: traits
+  - resource_provider_generation: resource_provider_generation
+
+Request example
+---------------
+
+.. literalinclude:: update-resource_provider-traits-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - traits: traits
+  - resource_provider_generation: resource_provider_generation
+
+Response Example
+----------------
+
+.. literalinclude:: update-resource_provider-traits.json
+   :language: javascript
+
+
+Delete resource provider traits
+===============================
+
+Dissociate all the traits from the resource provider identified by `{uuid}`.
+
+.. rest_method:: DELETE /resource_providers/{uuid}/traits
+
+Normal Response Codes: 204
+
+Error response codes: itemNotFound(404), conflict(409)
+
+* `409 Conflict` if the provider's traits are updated by another
+  thread while attempting the operation.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+No body content is returned on a successful DELETE.

placement-api-ref/source/update-resource_provider-traits-request.json

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

placement-api-ref/source/update-resource_provider-traits.json

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