Add api-ref for indicators API

Change-Id: Ie40f585b26efdd70b88f2e642698eb9e988e3d97
Story: 2007745
Task: 39923

7 files changed, 298 insertions, 0 deletions

diff --git a/api-ref/source/baremetal-api-v1-indicators.inc b/api-ref/source/baremetal-api-v1-indicators.inc
new file mode 100644
index 000000000..0c4b11885
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-indicators.inc
@@ -0,0 +1,154 @@
+.. -*- rst -*-
+
+=====================
+Indicators Management
+=====================
+
+The Indicators management is an extension of the node ReST API endpoint that
+allows reading and toggling the indicators (e.g. LEDs) on the hardware
+units.
+
+List Indicators
+===============
+
+.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators
+
+.. versionadded:: 1.63
+
+List all available indicator names for each of the hardware components.
+The components that the ``redfish`` driver may have are: ``system``,
+``chassis`` and ``drive``. The actual list depends on the support by the
+underlying hardware.
+
+Normal response code: 200
+
+Error response codes: 404 (if node not found)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - components: n_components
+   - name: component_name
+   - links: links
+
+**Example list of indicators for the node:**
+
+.. literalinclude:: samples/node-indicators-list-response.json
+   :language: javascript
+
+
+List Indicators for hardware component
+======================================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators/{component}
+
+.. versionadded:: 1.63
+
+Retrieves indicators for a given hardware component along with their attributes.
+The components that the ``redfish`` driver may have are: ``system``,
+``chassis`` and ``drive``. The actual list depends on the support by the
+underlying hardware.
+
+Normal response code: 200
+
+Error response codes: 404 (if node or component is not found)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+   - component: component
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - indicators: n_indicators
+   - name: indicator_name
+   - readonly: indicator_readonly
+   - states: indicator_states
+   - links: links
+
+**Example list of indicators for a given component of the node:**
+
+.. literalinclude:: samples/node-indicators-component-list-response.json
+   :language: javascript
+
+
+Get Indicator State
+===================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/management/indicators/{component}/{ind_ident}
+
+.. versionadded:: 1.63
+
+Retrieves the state of a chosen indicator for a given component of the node.
+The value of the field in the response object represents its state. The values
+can be one of  ``OFF``, ``ON``, ``BLINKING`` or ``UNKNOWN``.
+
+Normal response code: 200
+
+Error response codes: 404 (if node, component or indicator is not found)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - node_ident: node_ident
+  - component: component
+  - ind_ident: ind_ident
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - state: n_ind_state
+
+**Example list of indicators for a given component of the node:**
+
+.. literalinclude:: samples/node-indicators-get-state-response.json
+  :language: javascript
+
+
+Set Indicator State
+===================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/management/indicators/{component}/{ind_ident}
+
+.. versionadded:: 1.63
+
+Set the state of the desired indicators of the component.
+
+Normal response code: 204 (No content)
+
+Error codes:
+    - 400 (if state is not an accepted value)
+    - 404 (if node, component or indicator is not found)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+   - component: component
+   - ind_ident: ind_ident
+   - state: n_ind_state
+
+**Set the State of an Indicator**
+
+.. literalinclude:: samples/node-indicators-set-state.json
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 60c3faff0..b8f19267a 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -12,6 +12,7 @@
 .. include:: baremetal-api-v1-node-passthru.inc
 .. include:: baremetal-api-v1-nodes-traits.inc
 .. include:: baremetal-api-v1-nodes-vifs.inc
+.. include:: baremetal-api-v1-indicators.inc
 .. include:: baremetal-api-v1-portgroups.inc
 .. include:: baremetal-api-v1-nodes-portgroups.inc
 .. include:: baremetal-api-v1-ports.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 979417abd..86a380ff0 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -56,6 +56,12 @@ chassis_ident:
   in: path
   required: true
   type: string
+component:
+  description: |
+    The Bare Metal node component.
+  in: path
+  required: true
+  type: string
 deploy_template_ident:
   description: |
     The UUID or name of the deploy template.
@@ -74,6 +80,12 @@ hostname_ident:
   in: path
   required: true
   type: string
+ind_ident:
+  description: |
+    The indicator of a Bare Metal component.
+  in: path
+  required: true
+  type: string
 node_id:
   description: |
     The UUID of the node.
@@ -538,6 +550,12 @@ clean_steps:
   in: body
   required: false
   type: array
+component_name:
+  description: |
+    The name of the component available for the node.
+  in: body
+  required: true
+  type: string
 conductor:
   description: |
     The conductor currently servicing a node. This field is read-only.
@@ -855,6 +873,25 @@ id:
   in: body
   required: true
   type: string
+indicator_name:
+  description: |
+    The name of the indicator.
+  in: body
+  required: true
+  type: boolean
+indicator_readonly:
+  description: |
+    Indicates whether the indicator is readonly.
+  in: body
+  required: true
+  type: boolean
+indicator_states:
+  description: |
+    The possible states for a given indicator, the only values that can be
+    returned are:  ``ON``, ``OFF``, ``BLINKING`` and ``UNKNOWN``
+  in: body
+  required: true
+  type: string
 inspect_interface:
   description: |
     The interface used for node inspection, e.g. "no-inspect".
@@ -956,12 +993,33 @@ management_interface:
   in: body
   required: true
   type: string
+n_components:
+  description: |
+    List all available indicators names for each of the hardware components
+    for this node.
+  in: body
+  required: true
+  type: array
 n_description:
   description: |
     Informational text about this node.
   in: body
   required: true
   type: string
+n_ind_state:
+  description: |
+    The state of an indicator of the component of the node. Possible values
+    are: ``OFF``, ``ON``, ``BLINKING`` or ``UNKNOWN``.
+  in: body
+  required: true
+  type: string
+n_indicators:
+  description: |
+    Retrieves all indicators for a given hardware component along with their
+    attributes for this node.
+  in: body
+  required: true
+  type: array
 n_portgroups:
   description: |
     Links to the collection of portgroups on this node.
diff --git a/api-ref/source/samples/node-indicators-component-list-response.json b/api-ref/source/samples/node-indicators-component-list-response.json
new file mode 100644
index 000000000..51a3b4b16
--- /dev/null
+++ b/api-ref/source/samples/node-indicators-component-list-response.json
@@ -0,0 +1,45 @@
+{
+    "indicators": [
+        {
+            "name": "power",
+            "readonly": true,
+            "states": [
+                "OFF",
+                "ON"
+            ],
+            "links": [
+                {
+                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
+                    management/indicators/system/power",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://127.0.0.1:6385/nodes/Compute0/
+                    management/indicators/system/power",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        {
+            "name": "alert",
+            "readonly": false,
+            "states": [
+                "OFF",
+                "BLINKING",
+                "UNKNOWN"
+            ],
+            "links": [
+                {
+                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
+                    management/indicators/system/alert",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://127.0.0.1:6385/nodes/Compute0/
+                    management/indicators/system/alert",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+    ]
+}
diff --git a/api-ref/source/samples/node-indicators-get-state-response.json b/api-ref/source/samples/node-indicators-get-state-response.json
new file mode 100644
index 000000000..f4741def6
--- /dev/null
+++ b/api-ref/source/samples/node-indicators-get-state-response.json
@@ -0,0 +1,3 @@
+{
+  "state": "ON"
+}
diff --git a/api-ref/source/samples/node-indicators-list-response.json b/api-ref/source/samples/node-indicators-list-response.json
new file mode 100644
index 000000000..a813c26ab
--- /dev/null
+++ b/api-ref/source/samples/node-indicators-list-response.json
@@ -0,0 +1,34 @@
+{
+    "components": [
+        {
+            "name": "system",
+            "links": [
+                {
+                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
+                    management/indicators/system",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://127.0.0.1:6385/nodes/Compute0/
+                    management/indicators/system",
+                    "rel": "bookmark"
+                }
+            ]
+        },
+        {
+            "name": "chassis",
+            "links": [
+                {
+                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
+                    management/indicators/chassis",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://127.0.0.1:6385/nodes/Compute0/
+                    management/indicators/chassis",
+                    "rel": "bookmark"
+                }
+            ]
+        }
+    ]
+}
diff --git a/api-ref/source/samples/node-indicators-set-state.json b/api-ref/source/samples/node-indicators-set-state.json
new file mode 100644
index 000000000..26063ffe2
--- /dev/null
+++ b/api-ref/source/samples/node-indicators-set-state.json
@@ -0,0 +1,3 @@
+{
+  "state": "BLINKING"
+}