Merge "Revise api-ref docs"

api-ref/source/index.rst

@@ -1,8 +1,8 @@
 :tocdepth: 2
 
-=========================================
-Hardware Introspection for Bare Metal API
-=========================================
+============================================
+API of Hardware Introspection for Bare Metal
+============================================
 
 .. rest_expand_all::
 

api-ref/source/introspection-api-v1-continue.inc

@@ -5,14 +5,13 @@ Process introspection data
 ==========================
 
 After the ramdisk collects the required information from the bare metal
-node, it should post it back to Inspector via ``POST /v1/continue`` method.
-
+node, it should post it back to Inspector via ``POST /v1/continue`` API.
 
 .. warning::
     Operators are reminded not to expose the Ironic Inspector API to
-    unsecured networks. Below method is available to *unauthenticated*
-    clients because **ironic-python-agent** ramdisk does not have access to
-    keystone credentials.
+    unsecured and untrusted networks. API below is available to
+    *unauthenticated* clients because **ironic-python-agent** ramdisk
+    does not have access to keystone credentials.
 
 
 Ramdisk Callback
@@ -20,8 +19,8 @@ Ramdisk Callback
 
 .. rest_method::  POST /v1/continue
 
-It is internal method for the ramdisk to post back all discovered data.
-This should not be used for anything other than the ramdisk.
+It is the API for the ramdisk to post back all discovered data.
+This should not be used for clients other than the ramdisk.
 
 Full list of hardware inventory keys may be found in **ironic-python-agent**
 documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_.
@@ -45,7 +44,6 @@ List of mandatory hardware keys:
    - disks: disks
    - root_disk: root_disk
    - boot_interface: boot_interface
-   - logs: logs
 
 **Example node introspection continue request:**
 

api-ref/source/introspection-api-v1-introspection.inc

@@ -4,9 +4,10 @@
 Node Introspection
 ==================
 
-Start, abort introspection, get introspection status, get introspection data
-are done through the ``/v1/introspection`` resource. There are also several
-sub-resources, which allow further actions to be performed on introspection.
+Start, abort introspection, get introspection status, and get introspection
+data are done through the ``/v1/introspection`` resource. There are also
+several sub-resources, which allow further actions to be performed on
+introspection.
 
 Start Introspection
 ===================
@@ -16,8 +17,9 @@ Start Introspection
 Initiate hardware introspection for node {node_id} . All power management
 configuration for this node needs to be done prior to calling the endpoint.
 
-In case missing or invalid authentication response code will be 401 and 403.
-If Inspector don't find node {node_id}, it will return 404.
+In the case of missing or invalid authentication, the response code will be
+401 and 403 respectively.
+If Inspector doesn't find node {node_id}, it will return 404.
 
 Normal response codes: 202
 
@@ -64,7 +66,7 @@ Response
 --------
 
 The response will contain the complete introspection info, like
-create, finish time, introspection state, errors if any.
+start, finish time, introspection state, errors if any.
 
 .. rest_parameters:: parameters.yaml
 
@@ -197,13 +199,12 @@ Reapply Introspection on stored data
 
 .. rest_method::  POST /v1/introspection/{node_id}/data/unprocessed
 
-This method riggers introspection on stored unprocessed data.
+This method triggers introspection on stored unprocessed data.
 No data is allowed to be sent along with the request.
 
 .. note::
 
-    Requires enabling Swift store in processing section of the
-    configuration file.
+    Requires enabling introspection storage backend via ``[processing]store_data``.
 
 Normal response codes: 202
 

api-ref/source/introspection-api-v1-rules.inc

@@ -84,17 +84,6 @@ Response
    :language: javascript
 
 
-Delete Introspection Rules
-==========================
-
-.. rest_method::  DELETE /v1/rules
-
-Delete all introspection rules
-
-Normal response codes: 204
-
-
-
 Get Introspection Rule
 ======================
 
@@ -102,7 +91,7 @@ Get Introspection Rule
 
 Get one introspection rule by its ``uuid``
 
-Normal response codes: 202
+Normal response codes: 200
 
 Error codes:
 
@@ -134,6 +123,16 @@ The response will contain full rule object:
    :language: javascript
 
 
+Delete Introspection Rules
+==========================
+
+.. rest_method::  DELETE /v1/rules
+
+Delete all introspection rules
+
+Normal response codes: 204
+
+
 Delete Introspection Rule
 =========================
 

api-ref/source/parameters.yaml

@@ -191,7 +191,7 @@ name:
   required: true
   type: string
 node_uuid:
-  description: Ironic node uui
+  description: Ironic node UUID.
   in: body
   required: true
   type: string