From 53a4aa99c966e0ee7aaec7a6042a6523713649bc Mon Sep 17 00:00:00 2001
From: Naohiro Tamura <naohirot@jp.fujitsu.com>
Date: Mon, 23 Jan 2017 16:32:08 +0900
Subject: [PATCH] Add soft reboot, soft power off and power timeout to api-ref

This patch updates api-ref documentation with soft reboot, soft power
off and power timeout that were added in API microversion 1.27.

Partial-Bug: #1526226
Change-Id: I9b17da3e5e02f7e3de0c5c2b3dec1e81bf642391
---
 api-ref/source/baremetal-api-v1-node-management.inc | 11 ++++++++---
 api-ref/source/parameters.yaml                      | 10 +++++++++-
 api-ref/source/samples/node-set-soft-power-off.json |  4 ++++
 3 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 api-ref/source/samples/node-set-soft-power-off.json

diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc
index 791535ce72..2a53702487 100644
--- a/api-ref/source/baremetal-api-v1-node-management.inc
+++ b/api-ref/source/baremetal-api-v1-node-management.inc
@@ -296,11 +296,11 @@ Change Node Power State
 
 Request a change to the Node's power state.
 
-Normal response code: 202
+Normal response code: 202 (Accepted)
 
 Error codes:
     - 409 (NodeLocked, ClientError)
-    - 400 (InvalidState)
+    - 400 (Invalid, InvalidStateRequested, InvalidParameterValue)
     - 406 (NotAcceptable)
     - 503 (NoFreeConductorWorkers)
 
@@ -310,12 +310,17 @@ Request
 .. rest_parameters:: parameters.yaml
 
     - node_ident: node_ident
-    - target: power_state
+    - target: target_power_state
+    - timeout: power_timeout
 
 **Example request to power off a Node:**
 
 .. literalinclude:: samples/node-set-power-off.json
 
+**Example request to soft power off a Node with timeout:**
+
+.. literalinclude:: samples/node-set-soft-power-off.json
+
 
 Change Node Provision State
 ===========================
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 2cb1de4b56..816091da29 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -644,6 +644,12 @@ power_state:
   in: body
   required: true
   type: string
+power_timeout:
+  description: |
+    Timeout for a power state transition. Added in API microversion 1.27.
+  in: body
+  required: false
+  type: integer
 properties:
   description: |
     A list of links to driver properties.
@@ -728,7 +734,9 @@ supported_boot_devices:
 target_power_state:
   description: |
     If a power state transition has been requested, this field represents the
-    requested (ie, "target") state.
+    requested (ie, "target") state either "power on", "power off", or "rebooting".
+    Added new target power states "soft power off" and "soft rebooting" in API
+    microversion 1.27.
   in: body
   required: true
   type: string
diff --git a/api-ref/source/samples/node-set-soft-power-off.json b/api-ref/source/samples/node-set-soft-power-off.json
new file mode 100644
index 0000000000..9368bcff34
--- /dev/null
+++ b/api-ref/source/samples/node-set-soft-power-off.json
@@ -0,0 +1,4 @@
+{
+    "target": "soft power off",
+    'timeout': 300
+}