From 94813057a648a625ad0a52fdd03f6aef0065d4b0 Mon Sep 17 00:00:00 2001
From: Andrey Volkov <avolkov@mirantis.com>
Date: Wed, 14 Jun 2017 14:43:25 +0300
Subject: [PATCH] [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
---
 .../source/get-resource_provider-traits.json  |   7 ++
 placement-api-ref/source/index.rst            |   1 +
 .../source/resource_provider_traits.inc       | 115 ++++++++++++++++++
 ...date-resource_provider-traits-request.json |   7 ++
 .../update-resource_provider-traits.json      |   7 ++
 5 files changed, 137 insertions(+)
 create mode 100644 placement-api-ref/source/get-resource_provider-traits.json
 create mode 100644 placement-api-ref/source/resource_provider_traits.inc
 create mode 100644 placement-api-ref/source/update-resource_provider-traits-request.json
 create mode 100644 placement-api-ref/source/update-resource_provider-traits.json

diff --git a/placement-api-ref/source/get-resource_provider-traits.json b/placement-api-ref/source/get-resource_provider-traits.json
new file mode 100644
index 000000000..7f0b461f2
--- /dev/null
+++ b/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"
+    ]
+}
diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst
index 097e3fbd5..3773477fa 100644
--- a/placement-api-ref/source/index.rst
+++ b/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
diff --git a/placement-api-ref/source/resource_provider_traits.inc b/placement-api-ref/source/resource_provider_traits.inc
new file mode 100644
index 000000000..74bb20c4b
--- /dev/null
+++ b/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.
diff --git a/placement-api-ref/source/update-resource_provider-traits-request.json b/placement-api-ref/source/update-resource_provider-traits-request.json
new file mode 100644
index 000000000..ca2e2af00
--- /dev/null
+++ b/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"
+    ]
+}
diff --git a/placement-api-ref/source/update-resource_provider-traits.json b/placement-api-ref/source/update-resource_provider-traits.json
new file mode 100644
index 000000000..7f0b461f2
--- /dev/null
+++ b/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"
+    ]
+}