Follow up to api-ref revision

Addressing commments from https://review.openstack.org/#/c/613515

Contents about introspection sub resouces are moved to a new file.

Change-Id: Icd3efb902e6f836dad653011a96edc84a3feea7c

api-ref/source/index.rst

@@ -8,5 +8,6 @@ API of Hardware Introspection for Bare Metal
 
 .. include:: introspection-api-versions.inc
 .. include:: introspection-api-v1-introspection.inc
+.. include:: introspection-api-v1-introspection-management.inc
 .. include:: introspection-api-v1-continue.inc
 .. include:: introspection-api-v1-rules.inc

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

@@ -0,0 +1,100 @@
+.. -*- rst -*-
+
+========================================
+Introspection Management (introspection)
+========================================
+
+Abort introspection, get introspection data and reapply introspection can be
+done through introspection sub-resources.
+
+Abort Introspection
+===================
+
+.. rest_method::  POST /v1/introspection/{node_id}/abort
+
+Abort running introspection.
+
+Normal response codes: 202
+
+Error codes:
+
+* 400 - bad request
+* 401, 403 - missing or invalid authentication
+* 404 - node cannot be found
+* 409 - inspector has locked this node for processing
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+
+
+Get Introspection data
+======================
+
+.. rest_method::  GET /v1/introspection/{node_id}/data
+
+Return stored data from successful introspection.
+
+.. note::
+    We do not provide any backward compatibility guarantees regarding the
+    format and contents of the stored data. Notably, it depends on the ramdisk
+    used and plugins enabled both in the ramdisk and in inspector itself.
+
+Normal response codes: 200
+
+Error codes:
+
+* 400 - bad request
+* 401, 403 - missing or invalid authentication
+* 404 - data cannot be found or data storage not configured
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_id: node_id
+
+
+Response
+--------
+
+The response will contain introspection data in the form of json string.
+
+**Example JSON representation of an introspection data:**
+
+.. literalinclude:: samples/api-v1-data-introspection-response.json
+   :language: javascript
+
+
+Reapply Introspection on stored data
+====================================
+
+.. rest_method::  POST /v1/introspection/{node_id}/data/unprocessed
+
+This method triggers introspection on stored unprocessed data.
+No data is allowed to be sent along with the request.
+
+.. note::
+
+    Requires enabling introspection storage backend via ``[processing]store_data``.
+
+Normal response codes: 202
+
+Error codes:
+
+* 400 - bad request or store not configured
+* 401, 403 - missing or invalid authentication
+* 404 - node not found for Node ID
+* 409 - inspector locked node for processing
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - node_id: node_id

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

@@ -1,13 +1,12 @@
 .. -*- rst -*-
 
-==================
+==================================
-Node Introspection
+Node Introspection (introspection)
-==================
+==================================
 
-Start, abort introspection, get introspection status, and get introspection
+Start introspection, get introspection status are done through the
-data are done through the ``/v1/introspection`` resource. There are also
+``/v1/introspection`` resource. There are also several sub-resources, which
-several sub-resources, which allow further actions to be performed on
+allow further actions to be performed on introspection.
-introspection.
 
 Start Introspection
 ===================
@@ -35,55 +34,6 @@ Request
    - manage_boot: manage_boot
 
 
-Response
---------
-
-The response will be empty body.
-
-Get Introspection status
-========================
-
-.. rest_method::  GET /v1/introspection/{node_id}
-
-Get node introspection status.
-
-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.
-
-Normal response codes: 200
-
-Error codes: 400, 401, 403, 404
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - node_id: node_id
-
-
-Response
---------
-
-The response will contain the complete introspection info, like
-start, finish time, introspection state, errors if any.
-
-.. rest_parameters:: parameters.yaml
-
-   - error: error
-   - finished: finished
-   - finished_at: finished_at
-   - links: links
-   - started_at: started_at
-   - state: state
-   - uuid: node_id
-
-**Example JSON representation of an introspection:**
-
-.. literalinclude:: samples/api-v1-get-introspection-response.json
-   :language: javascript
-
-
 List All Introspection statuses
 ===============================
 
@@ -131,49 +81,19 @@ The response will contain a list of status objects:
    :language: javascript
 
 
-Abort Introspection
+Show Introspection status
-===================
+=========================
 
-.. rest_method::  POST /v1/introspection/{node_id}/abort
+.. rest_method::  GET /v1/introspection/{node_id}
 
-Abort running introspection.
+Show node introspection status.
 
-Normal response codes: 202
+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.
-Error codes:
-
-* 400 - bad request
-* 401, 403 - missing or invalid authentication
-* 404 - node cannot be found
-* 409 - inspector has locked this node for processing
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - node_id: node_id
-
-
-Get Introspection data
-======================
-
-.. rest_method::  GET /v1/introspection/{node_id}/data
-
-Return stored data from successful introspection.
-
-.. note::
-    We do not provide any backward compatibility guarantees regarding the
-    format and contents of the stored data. Notably, it depends on the ramdisk
-    used and plugins enabled both in the ramdisk and in inspector itself.
 
 Normal response codes: 200
 
-Error codes:
+Error codes: 400, 401, 403, 404
-
-* 400 - bad request
-* 401, 403 - missing or invalid authentication
-* 404 - data cannot be found or data storage not configured
 
 Request
 -------
@@ -186,39 +106,22 @@ Request
 Response
 --------
 
-The response will contain introspection data in the form of json string.
+The response will contain the complete introspection info, like
-
+start, finish time, introspection state, errors if any.
-**Example JSON representation of an introspection data:**
-
-.. literalinclude:: samples/api-v1-data-introspection-response.json
-   :language: javascript
-
-
-Reapply Introspection on stored data
-====================================
-
-.. rest_method::  POST /v1/introspection/{node_id}/data/unprocessed
-
-This method triggers introspection on stored unprocessed data.
-No data is allowed to be sent along with the request.
-
-.. note::
-
-    Requires enabling introspection storage backend via ``[processing]store_data``.
-
-Normal response codes: 202
-
-Error codes:
-
-* 400 - bad request or store not configured
-* 401, 403 - missing or invalid authentication
-* 404 - node not found for Node ID
-* 409 - inspector locked node for processing
-
-
-Request
--------
 
 .. rest_parameters:: parameters.yaml
 
-  - node_id: node_id
+   - error: error
+   - finished: finished
+   - finished_at: finished_at
+   - links: links
+   - started_at: started_at
+   - state: state
+   - uuid: node_id
+
+**Example JSON representation of an introspection:**
+
+.. literalinclude:: samples/api-v1-get-introspection-response.json
+   :language: javascript
+
+

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

@@ -5,7 +5,8 @@ Introspection Rules
 ===================
 
 Simple JSON-based DSL to define rules, which run during introspection.
-
+See `<https://docs.openstack.org/ironic-inspector/latest/user/usage.html#introspection-rules>`_
+for more information on rules.
 
 Create Introspection Rule
 =========================