Add API Reference for Watcher

This patch set adds API Reference along with some
fixes to documentation. It partially fixes bug #1757423.

Change-Id: I107b4fd5daf40aad63fc13864debbbbc82a9826c

api-ref/source/watcher-api-v1-actionplans.inc

@@ -0,0 +1,209 @@
+.. -*- rst -*-
+
+============
+Action Plans
+============
+
+An ``Action Plan`` specifies a flow of ``Actions`` that should be executed
+in order to satisfy a given ``Goal``. It also contains an estimated
+``global efficacy`` alongside a set of ``efficacy indicators``.
+
+An ``Action Plan`` is generated by Watcher when an ``Audit`` is successful
+which implies that the ``Strategy`` which was used has found a ``Solution``
+to achieve the ``Goal`` of this ``Audit``.
+
+In the default implementation of Watcher, an action plan is composed of
+a graph of linked ``Actions``. Each action may have parent actions, which
+should be executed prior to child action.
+
+Start Action Plan
+=================
+
+.. rest_method::  POST /v1/action_plans/{actionplan_ident}/start
+
+Starts a created Action Plan resource.
+
+Normal response codes: 200
+
+Error codes: 400,404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - actionplan_ident: actionplan_ident
+
+Response
+--------
+
+The list and example below are representative of the response as of API
+version 1:
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - state: actionplan_state
+    - audit_uuid: actionplan_audit_uuid
+    - strategy_uuid: strategy_uuid
+    - strategy_name: strategy_name
+    - efficacy_indicators: actionplan_efficacy_indicators
+    - global_efficacy: actionplan_global_efficacy
+    - links: links
+
+**Example JSON representation of an Action Plan:**
+
+.. literalinclude:: samples/actionplan-start-response.json
+   :language: javascript
+
+List Action Plan
+================
+
+.. rest_method::  GET /v1/action_plans
+
+Returns a list of Action Plan resources.
+
+Normal response codes: 200
+
+Error codes: 400,401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - audit_uuid: r_audit
+   - strategy: r_strategy
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - state: actionplan_state
+    - audit_uuid: actionplan_audit_uuid
+    - strategy_uuid: strategy_uuid
+    - strategy_name: strategy_name
+    - efficacy_indicators: actionplan_efficacy_indicators
+    - global_efficacy: actionplan_global_efficacy
+    - links: links
+
+**Example JSON representation of an Action Plan:**
+
+.. literalinclude:: samples/actionplan-list-response.json
+   :language: javascript
+
+Show Action Plan
+================
+
+.. rest_method::  GET /v1/action_plans/{actionplan_ident}
+
+Shows details for an Action Plan.
+
+Normal response codes: 200
+
+Error codes: 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - actionplan_ident: actionplan_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - state: actionplan_state
+    - audit_uuid: actionplan_audit_uuid
+    - strategy_uuid: strategy_uuid
+    - strategy_name: strategy_name
+    - efficacy_indicators: actionplan_efficacy_indicators
+    - global_efficacy: actionplan_global_efficacy
+    - links: links
+
+**Example JSON representation of an Audit:**
+
+.. literalinclude:: samples/actionplan-show-response.json
+   :language: javascript
+
+Cancel Action Plan
+==================
+
+.. rest_method::  PATCH /v1/action_plans/{actionplan_ident}
+
+Cancels a created Action Plan resource.
+
+.. note:
+    If Action Plan is in ONGOING state, then ``state`` attribute should be
+    replaced with ``CANCELLING`` value. Otherwise, ``CANCELLED`` is to be
+    used.
+
+Normal response codes: 200
+
+Error codes: 400,404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - actionplan_ident: actionplan_ident
+
+**Example Action Plan ONGOING cancelling request:**
+
+.. literalinclude:: samples/actionplan-cancel-request-cancelling.json
+   :language: javascript
+
+**Example Action Plan PENDING cancelling request:**
+
+.. literalinclude:: samples/actionplan-cancel-request-pending.json
+   :language: javascript
+
+Response
+--------
+
+The list and example below are representative of the response as of API
+version 1:
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - state: actionplan_state
+    - audit_uuid: actionplan_audit_uuid
+    - strategy_uuid: strategy_uuid
+    - strategy_name: strategy_name
+    - efficacy_indicators: actionplan_efficacy_indicators
+    - global_efficacy: actionplan_global_efficacy
+    - links: links
+
+**Example JSON representation of an Action Plan:**
+
+.. literalinclude:: samples/actionplan-start-response.json
+   :language: javascript
+
+Delete Action Plan
+==================
+
+.. rest_method::  DELETE /v1/action_plans/{actionplan_ident}
+
+Deletes an Action Plan. Action Plan can be deleted only from SUCCEEDED, RECOMMENDED, FAILED, SUPERSEDED, CANCELLED states.
+
+Normal response codes: 204
+
+Error codes: 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - actionplan_ident: actionplan_ident