From 4e1d732f4c80ec71b639144da7539b51cebf205d Mon Sep 17 00:00:00 2001
From: Andrey Volkov <avolkov@mirantis.com>
Date: Mon, 3 Apr 2017 11:30:03 +0300
Subject: [PATCH] [placement] Add api-ref for PUT RP inventories

This provides simple documentation of the request and response body
parameters when setting or replacing all inventories for a resource provider.

Change-Id: I720f5b6792b9f4ced905aef31715a835b07be504
---
 placement-api-ref/source/inventories.inc      | 53 +++++++++++++++++++
 placement-api-ref/source/parameters.yaml      | 23 ++++++--
 .../source/update-inventories-request.json    | 16 ++++++
 .../source/update-inventories.json            | 21 ++++++++
 4 files changed, 109 insertions(+), 4 deletions(-)
 create mode 100644 placement-api-ref/source/update-inventories-request.json
 create mode 100644 placement-api-ref/source/update-inventories.json

diff --git a/placement-api-ref/source/inventories.inc b/placement-api-ref/source/inventories.inc
index 2fff18936e75..a82bcefaecc0 100644
--- a/placement-api-ref/source/inventories.inc
+++ b/placement-api-ref/source/inventories.inc
@@ -42,3 +42,56 @@ Response Example
 
 .. literalinclude:: get-inventories.json
    :language: javascript
+
+Update resource provider inventories
+====================================
+
+Replaces the set of inventory records for the resource provider identified by `{uuid}`.
+
+.. rest_method:: PUT /resource_providers/{uuid}/inventories
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+  - resource_provider_generation: resource_provider_generation
+  - inventories: inventories
+  - allocation_ratio: allocation_ratio_opt
+  - max_unit: max_unit_opt
+  - min_unit: min_unit_opt
+  - reserved: reserved_opt
+  - step_size: step_size_opt
+  - total: total
+
+Request example
+---------------
+
+.. literalinclude:: update-inventories-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_provider_generation: resource_provider_generation
+  - inventories: inventories
+  - allocation_ratio: allocation_ratio
+  - max_unit: max_unit
+  - min_unit: min_unit
+  - reserved: reserved
+  - step_size: step_size
+  - total: total
+
+Response Example
+----------------
+
+.. literalinclude:: update-inventories.json
+   :language: javascript
+
diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml
index df12d732fe21..ddd04e50308d 100644
--- a/placement-api-ref/source/parameters.yaml
+++ b/placement-api-ref/source/parameters.yaml
@@ -37,7 +37,7 @@ resources_query:
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
 
 # variables in body
-allocation_ratio:
+allocation_ratio: &allocation_ratio
   type: float
   in: body
   required: true
@@ -51,6 +51,9 @@ allocation_ratio:
         total = 8
 
     Overall capacity is equal to 128 vCPUs.
+allocation_ratio_opt:
+  <<: *allocation_ratio
+  required: false
 inventories:
   type: object
   in: body
@@ -63,18 +66,27 @@ max_unit: &max_unit
   required: true
   description: >
     A maximum amount any single allocation against an inventory can have.
-min_unit:
+max_unit_opt:
+  <<: *max_unit
+  required: false
+min_unit: &min_unit
   type: integer
   in: body
   required: true
   description: >
     A minimum amount any single allocation against an inventory can have.
-reserved:
+min_unit_opt:
+  <<: *min_unit
+  required: false
+reserved: &reserved
   type: integer
   in: body
   required: true
   description: >
     The amount of the resource a provider has reserved for its own use.
+reserved_opt:
+  <<: *reserved
+  required: false
 resource_class:
   type: string
   in: body
@@ -109,7 +121,7 @@ resource_providers:
   required: true
   description: >
     A list of ``resource_provider`` objects.
-step_size:
+step_size: &step_size
   type: integer
   in: body
   required: true
@@ -117,6 +129,9 @@ step_size:
     A representation of the divisible amount of the resource
     that may be requested. For example, step_size = 5 means
     that only values divisible by 5 (5, 10, 15, etc.) can be requested.
+step_size_opt:
+  <<: *step_size
+  required: false
 total:
   type: integer
   in: body
diff --git a/placement-api-ref/source/update-inventories-request.json b/placement-api-ref/source/update-inventories-request.json
new file mode 100644
index 000000000000..cc336e974822
--- /dev/null
+++ b/placement-api-ref/source/update-inventories-request.json
@@ -0,0 +1,16 @@
+{
+    "inventories": {
+        "MEMORY_MB": {
+            "allocation_ratio": 2.0,
+            "max_unit": 16,
+            "step_size": 4,
+            "total": 128
+        },
+        "VCPU": {
+            "allocation_ratio": 10.0,
+            "reserved": 2,
+            "total": 64
+        }
+    },
+    "resource_provider_generation": 1
+}
diff --git a/placement-api-ref/source/update-inventories.json b/placement-api-ref/source/update-inventories.json
new file mode 100644
index 000000000000..9731eaee41ef
--- /dev/null
+++ b/placement-api-ref/source/update-inventories.json
@@ -0,0 +1,21 @@
+{
+    "inventories": {
+        "MEMORY_MB": {
+            "allocation_ratio": 2.0,
+            "max_unit": 16,
+            "min_unit": 1,
+            "reserved": 0,
+            "step_size": 4,
+            "total": 128
+        },
+        "VCPU": {
+            "allocation_ratio": 10.0,
+            "max_unit": 2147483647,
+            "min_unit": 1,
+            "reserved": 2,
+            "step_size": 1,
+            "total": 64
+        }
+    },
+    "resource_provider_generation": 2
+}