consolidated docs

Issue-ID: OPTFRA-242

Change-Id: I1440436559496cf688c66a13accdaeb0df0160c9
Signed-off-by: fsandoval <frank.sandoval@oamtechnologies.com>

2 files changed, 581 insertions, 49 deletions

diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst
deleted file mode 100644
index bfe8480..0000000
--- a/docs/sections/delivery.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Delivery
-=============================================
-
-    Delivery description TBD
\ No newline at end of file
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
index 7ef44e9..9ffb6fb 100644
--- a/docs/sections/offeredapis.rst
+++ b/docs/sections/offeredapis.rst
@@ -66,7 +66,7 @@ List all Homing API versions
 This operation does not accept a request body.
 
 Plans
-------------------
+-----
 
 Create a plan
 -------------
@@ -90,50 +90,588 @@ consisting of:
 -  **Optimizations** to further narrow down the remaining candidates
 
 The response contains an inventory **plan**, consisting of one or more
-sets of recommended pairings of demands with an inventory candidate’s
+sets of recommended pairings of demands with an inventory candidate's
 attributes and region.
 
 Request Parameters
 ~~~~~~~~~~~~~~~~~~
 
-+--------------------+------------+----------+------------------------+
-| Parameter          | Style      | Type     | Description            |
-+====================+============+==========+========================+
-| ``name``           | plain      | xsd:stri | A name for the new     |
-| (Optional)         |            | ng       | plan. If a name is not |
-|                    |            |          | provided, it will be   |
-|                    |            |          | auto-generated based   |
-|                    |            |          | on the homing          |
-|                    |            |          | template. This name    |
-|                    |            |          | must be unique within  |
-|                    |            |          | a given Conductor      |
-|                    |            |          | environment. When      |
-|                    |            |          | deleting a plan, its   |
-|                    |            |          | name will not become   |
-|                    |            |          | available for reuse    |
-|                    |            |          | until the deletion     |
-|                    |            |          | completes              |
-|                    |            |          | successfully. Must     |
-|                    |            |          | only contain letters,  |
-|                    |            |          | numbers, hypens, full  |
-|                    |            |          | stops, underscores,    |
-|                    |            |          | and tildes (RFC 3986,  |
-|                    |            |          | Section 2.3). This     |
-|                    |            |          | parameter is           |
-|                    |            |          | immutable.             |
-+--------------------+------------+----------+------------------------+
-| ``id`` (Optional)  | plain      | csapi:UU | The UUID of the plan.  |
-|                    |            | ID       | UUID is assigned by    |
-|                    |            |          | Conductor if no id is  |
-|                    |            |          | provided in the        |
-|                    |            |          | request.               |
-+--------------------+------------+----------+------------------------+
-| ``transaction_id`` | plain      | csapi:UU | The transaction id     |
-|                    |            | ID       | assigned by SO. The    |
-|                    |            |          | logs should have this  |
-|                    |            |          | transaction id for     |
-|                    |            |          | tracking purposes.     |
-+--------------------+------------+----------+------------------------+
-| ``files``          | plain      | xsd:dict | Supplies the contents  |
-| (Optional)         |            |          | of files referenced.   |
-+--------------------+------------+----------+------------------------+
\ No newline at end of file
++--------------------+-------+------------+-------------------+
+| Parameter          | Style | Type       | Description       |
++====================+=======+============+===================+
+| ``name``           | plain | xsd:string | A name for the    |
+| (Optional)         |       |            | new plan. If a    |
+|                    |       |            | name is not       |
+|                    |       |            | provided, it      |
+|                    |       |            | will be           |
+|                    |       |            | auto-generated    |
+|                    |       |            | based on the      |
+|                    |       |            | homing            |
+|                    |       |            | template. This    |
+|                    |       |            | name must be      |
+|                    |       |            | unique within     |
+|                    |       |            | a given           |
+|                    |       |            | Conductor         |
+|                    |       |            | environment.      |
+|                    |       |            | When deleting     |
+|                    |       |            | a plan, its       |
+|                    |       |            | name will not     |
+|                    |       |            | become            |
+|                    |       |            | available for     |
+|                    |       |            | reuse until       |
+|                    |       |            | the deletion      |
+|                    |       |            | completes         |
+|                    |       |            | successfully.     |
+|                    |       |            | Must only         |
+|                    |       |            | contain           |
+|                    |       |            | letters,          |
+|                    |       |            | numbers,          |
+|                    |       |            | hypens, full      |
+|                    |       |            | stops,            |
+|                    |       |            | underscores,      |
+|                    |       |            | and tildes        |
+|                    |       |            | (RFC 3986,        |
+|                    |       |            | Section 2.3).     |
+|                    |       |            | This parameter    |
+|                    |       |            | is immutable.     |
++--------------------+-------+------------+-------------------+
+| ``id``             | plain | csapi:UUID | The UUID of       |
+| (Optional)         |       |            | the plan. UUID    |
+|                    |       |            | is assigned by    |
+|                    |       |            | Conductor if      |
+|                    |       |            | no id is          |
+|                    |       |            | provided in       |
+|                    |       |            | the request.      |
++--------------------+-------+------------+-------------------+
+| ``transaction_id`` | plain | csapi:UUID | The               |
+|                    |       |            | transaction id    |
+|                    |       |            | assigned by       |
+|                    |       |            | MSO. The logs     |
+|                    |       |            | should have       |
+|                    |       |            | this              |
+|                    |       |            | transaction id    |
+|                    |       |            | for tracking      |
+|                    |       |            | purposes.         |
++--------------------+-------+------------+-------------------+
+| ``files``          | plain | xsd:dict   | Supplies the      |
+| (Optional)         |       |            | contents of       |
+|                    |       |            | files             |
+|                    |       |            | referenced in     |
+|                    |       |            | the template.     |
+|                    |       |            | Conductor         |
+|                    |       |            | templates can     |
+|                    |       |            | explicitly        |
+|                    |       |            | reference         |
+|                    |       |            | files by using    |
+|                    |       |            | the               |
+|                    |       |            | ``get_file``      |
+|                    |       |            | intrinsic         |
+|                    |       |            | function. The     |
+|                    |       |            | value is a        |
+|                    |       |            | JSON object,      |
+|                    |       |            | where each key    |
+|                    |       |            | is a relative     |
+|                    |       |            | or absolute       |
+|                    |       |            | URI which         |
+|                    |       |            | serves as the     |
+|                    |       |            | name of a         |
+|                    |       |            | file, and the     |
+|                    |       |            | associated        |
+|                    |       |            | value provides    |
+|                    |       |            | the contents      |
+|                    |       |            | of the file.      |
+|                    |       |            | Additionally,     |
+|                    |       |            | some template     |
+|                    |       |            | authors encode    |
+|                    |       |            | their user        |
+|                    |       |            | data in a         |
+|                    |       |            | local file.       |
+|                    |       |            | The Homing        |
+|                    |       |            | client (e.g.,     |
+|                    |       |            | a CLI) can        |
+|                    |       |            | examine the       |
+|                    |       |            | template for      |
+|                    |       |            | the               |
+|                    |       |            | ``get_file``      |
+|                    |       |            | intrinsic         |
+|                    |       |            | function          |
+|                    |       |            | (e.g.,            |
+|                    |       |            | ``{get_file: f    |
+|                    |       |            | ile.yaml}``)      |
+|                    |       |            | and add an        |
+|                    |       |            | entry to the      |
+|                    |       |            | ``files`` map     |
+|                    |       |            | with the path     |
+|                    |       |            | to the file as    |
+|                    |       |            | the name and      |
+|                    |       |            | the file          |
+|                    |       |            | contents as       |
+|                    |       |            | the value. Do     |
+|                    |       |            | not use this      |
+|                    |       |            | parameter to      |
+|                    |       |            | provide the       |
+|                    |       |            | content of the    |
+|                    |       |            | template          |
+|                    |       |            | located at the    |
+|                    |       |            | ``template_url``  |
+|                    |       |            | address.          |
+|                    |       |            | Instead, use      |
+|                    |       |            | the               |
+|                    |       |            | ``template``      |
+|                    |       |            | parameter to      |
+|                    |       |            | supply the        |
+|                    |       |            | template          |
+|                    |       |            | content as        |
+|                    |       |            | part of the       |
+|                    |       |            | request.          |
++--------------------+-------+------------+-------------------+
+| ``template_url``   | plain | xsd:string | A URI to          |
+| (Optional)         |       |            | the location      |
+|                    |       |            | containing the    |
+|                    |       |            | template on       |
+|                    |       |            | which to          |
+|                    |       |            | perform the       |
+|                    |       |            | operation. See    |
+|                    |       |            | the               |
+|                    |       |            | description of    |
+|                    |       |            | the               |
+|                    |       |            | ``template``      |
+|                    |       |            | parameter for     |
+|                    |       |            | information       |
+|                    |       |            | about the         |
+|                    |       |            | expected          |
+|                    |       |            | template          |
+|                    |       |            | content           |
+|                    |       |            | located at the    |
+|                    |       |            | URI. This         |
+|                    |       |            | parameter is      |
+|                    |       |            | only required     |
+|                    |       |            | when you omit     |
+|                    |       |            | the               |
+|                    |       |            | ``template``      |
+|                    |       |            | parameter. If     |
+|                    |       |            | you specify       |
+|                    |       |            | both              |
+|                    |       |            | parameters,       |
+|                    |       |            | this parameter    |
+|                    |       |            | is ignored.       |
++--------------------+-------+------------+-------------------+
+| ``template``       | plain | xsd:string | The template      |
+|                    |       | or xsd:dict| on which to       |
+|                    |       |            | perform the       |
+|                    |       |            | operation. See    |
+|                    |       |            | the Homing        |
+|                    |       |            | Template          |
+|                    |       |            | Guide             |
+|                    |       |            | for complete      |
+|                    |       |            | information on    |
+|                    |       |            | the format.       |
+|                    |       |            | This parameter    |
+|                    |       |            | is either         |
+|                    |       |            | provided as a     |
+|                    |       |            | ``string`` or     |
+|                    |       |            | ``dict`` in       |
+|                    |       |            | the JSON          |
+|                    |       |            | request body.     |
+|                    |       |            | For ``string``    |
+|                    |       |            | content it may    |
+|                    |       |            | be a JSON- or     |
+|                    |       |            | YAML-formatted    |
+|                    |       |            | Conductor         |
+|                    |       |            | template. For     |
+|                    |       |            | ``dict``          |
+|                    |       |            | content it        |
+|                    |       |            | must be a         |
+|                    |       |            | direct JSON       |
+|                    |       |            | representation    |
+|                    |       |            | of the            |
+|                    |       |            | Conductor         |
+|                    |       |            | template. This    |
+|                    |       |            | parameter is      |
+|                    |       |            | required only     |
+|                    |       |            | when you omit     |
+|                    |       |            | the               |
+|                    |       |            | ``template_url``  |
+|                    |       |            | parameter. If     |
+|                    |       |            | you specify       |
+|                    |       |            | both              |
+|                    |       |            | parameters,       |
+|                    |       |            | this value        |
+|                    |       |            | overrides the     |
+|                    |       |            | ``template_url``  |
+|                    |       |            | parameter         |
+|                    |       |            | value.            |
++--------------------+-------+------------+-------------------+
+| ``timeout``        | plain | xsd:number | The timeout       |
+| (Optional)         |       |            | for plan          |
+|                    |       |            | creation in       |
+|                    |       |            | minutes.          |
+|                    |       |            | Default is 1.     |
++--------------------+-------+------------+-------------------+
+| ``limit``          | plain | xsd:number | The maximum       |
+| (Optional)         |       |            | number of         |
+|                    |       |            | recommendations   |
+|                    |       |            | to return.        |
+|                    |       |            | Default is 1.     |
++--------------------+-------+------------+-------------------+
+
+**NOTE**: ``files``, ``template_url``, and ``timeout`` are not yet
+supported.
+
+Response Parameters
+~~~~~~~~~~~~~~~~~~~
+
++--------------------+----------+------------+--------------------+
+| Parameter          | Style    | Type       | Description        |
++====================+==========+============+====================+
+| ``plan``           | plain    | xsd:dict   | The ``plan``       |
+|                    |          |            | object.            |
++--------------------+----------+------------+--------------------+
+| ``id``             | plain    | csapi:UUID | The UUID of        |
+|                    |          |            | the plan.          |
++--------------------+----------+------------+--------------------+
+| ``transaction_id`` | plain    | csapi:UUID | The                |
+|                    |          |            | transaction id     |
+|                    |          |            | assigned by        |
+|                    |          |            | the MSO.           |
++--------------------+----------+------------+--------------------+
+| ``name``           | plain    | xsd:string | The plan name.     |
+|                    |          |            |                    |
++--------------------+----------+------------+--------------------+
+| ``status``         | plain    | xsd:string | The plan           |
+|                    |          |            | status. One of     |
+|                    |          |            | ``template``,      |
+|                    |          |            | ``translated``,    |
+|                    |          |            | ``solving``,       |
+|                    |          |            | ``solved``, or     | 
+|                    |          |            | ``error``. See     |
+|                    |          |            | **Plan             |
+|                    |          |            | Status** table     |
+|                    |          |            | for                |
+|                    |          |            | descriptions       |
+|                    |          |            | of each value.     |
++--------------------+----------+------------+--------------------+
+| ``message``        | plain    | xsd:string | Additional         |
+|                    |          |            | context, if        |
+|                    |          |            | any, around        |
+|                    |          |            | the message        |
+|                    |          |            | status. If the     |
+|                    |          |            | status is          |
+|                    |          |            | ``error``,         |
+|                    |          |            | this may           |
+|                    |          |            | include a          |
+|                    |          |            | reason and         |
+|                    |          |            | suggested          |
+|                    |          |            | remediation,       |
+|                    |          |            | if available.      |
++--------------------+----------+------------+--------------------+
+| ``links``          | plain    | xsd:list   | A list of URLs     |
+|                    |          |            | for the plan.      |
+|                    |          |            | Each URL is a      |
+|                    |          |            | JSON object        |
+|                    |          |            | with an            |
+|                    |          |            | ``href`` key       |
+|                    |          |            | indicating the     |
+|                    |          |            | URL and a          |
+|                    |          |            | ``rel`` key        |
+|                    |          |            | indicating its     |
+|                    |          |            | relationship       |
+|                    |          |            | to the plan in     |
+|                    |          |            | question.          |
+|                    |          |            | There may be       |
+|                    |          |            | multiple links     |
+|                    |          |            | returned. The      |
+|                    |          |            | ``self``           |
+|                    |          |            | relationship       |
+|                    |          |            | identifies the     |
+|                    |          |            | URL of the         |
+|                    |          |            | plan itself.       |
++--------------------+----------+------------+--------------------+
+| ``recommendations``| plain    | xsd:list   | A list of one      |
+|                    |          |            | or more            |
+|                    |          |            | recommendationS.   |
+|                    |          |            | A                  |
+|                    |          |            | recommendation     |
+|                    |          |            | pairs each         |
+|                    |          |            | requested          |
+|                    |          |            | demand with an     |
+|                    |          |            | inventory          |
+|                    |          |            | provider, a        |
+|                    |          |            | single             |
+|                    |          |            | candidate, and     |
+|                    |          |            | an opaque          |
+|                    |          |            | dictionary of      |
+|                    |          |            | attributes.        |
+|                    |          |            | Refer to the       |
+|                    |          |            | Demand             |
+|                    |          |            | candidate          |
+|                    |          |            | schema in the      |
+|                    |          |            | Homing             |
+|                    |          |            | Template           |
+|                    |          |            | Guide              |
+|                    |          |            | for further        |
+|                    |          |            | details. (Note     |
+|                    |          |            | that, when         |
+|                    |          |            | ``inventory_type`` |
+|                    |          |            | is ``cloud``       |
+|                    |          |            | the                |
+|                    |          |            | candidate's        |
+|                    |          |            | ``candidate_id``   |
+|                    |          |            | field is           |
+|                    |          |            | redundant and      |
+|                    |          |            | thus omitted.)     |
++--------------------+----------+------------+--------------------+  
+
+Plan Status
+~~~~~~~~~~~
+
++----------------+-----------------+
+| Status         | Description     |
++================+=================+
+| ``template``   | Plan request    |
+|                | and homing      |
+|                | template have   |
+|                | been received.  |
+|                | Awaiting        |
+|                | translation.    |
++----------------+-----------------+
+| ``translated`` | Homing          |
+|                | template has    |
+|                | been            |
+|                | translated,     |
+|                | and candidates  |
+|                | have been       |
+|                | obtained from   |
+|                | inventory       |
+|                | providers.      |
+|                | Awaiting        |
+|                | solving.        |
++----------------+-----------------+
+| ``solving``    | Search for a    |
+|                | solution is in  |
+|                | progress. This  |
+|                | may             |
+|                | incorporate     |
+|                | requests to     |
+|                | service         |
+|                | controllers     |
+|                | for additional  |
+|                | information.    |
++----------------+-----------------+
+| ``solved``     | Search is       |
+|                | complete. A     |
+|                | solution with   |
+|                | one or more     |
+|                | recommendations |
+|                | was found.      |
++----------------+-----------------+
+| ``not found``  | Search is       |
+|                | complete. No    |
+|                | recommendations |
+|                | were found.     |
++----------------+-----------------+
+| ``error``      | An error was    |
+|                | encountered.    |
++----------------+-----------------+
+
+State Diagram
+^^^^^^^^^^^^^
+
+.. code:: text
+
+                      ----------------------------------------
+                     |                                        |
+                     |                   /---> solved ---> reserving ---> done
+                     |                  /                    /
+     template -> translated -> solving ------> not found    /
+         |         ^               |    \                  / 
+         |         | conditionally |     \---> error <----/
+         |         |   (see note)  |             ^
+         |         \---------------/             |
+         \---------------------------------------/
+
+**NOTE**: When Conductor's solver service is started in non-concurrent
+mode (the default), it will reset any plans found waiting and stuck in
+the ``solving`` state back to ``translated``.
+
+.. code:: json
+
+    {
+      "name": "PLAN_NAME",
+      "template": "CONDUCTOR_TEMPLATE",
+      "limit": 3
+    }
+
+.. code:: json
+
+    {
+      "plan": {
+        "name": "PLAN_NAME",
+        "id": "ee1c5269-c7f0-492a-8652-f0ceb15ed3bc",
+        "transaction_id": "6bca5f2b-ee7e-4637-8b58-1b4b36ed10f9",
+        "status": "solved",
+        "message", "Plan PLAN_NAME is solved.",
+        "links": [
+          {
+            "href": "http://homing/v1/plans/ee1c5269-c7f0-492a-8652-f0ceb15ed3bc",
+            "rel": "self"
+          }
+        ],
+        "recommendations": [
+          {
+            "DEMAND_NAME_1": {
+              "inventory_provider": "aai",
+              "service_resource_id": "4feb0545-69e2-424c-b3c4-b270e5f2a15d",
+              "candidate": {
+                "candidate_id": "99befee8-e8c0-425b-8f36-fb7a8098d9a9",
+                "inventory_type": "service",
+                "location_type": "aic",
+                "location_id": "dal01",
+                "host_id" : "vig20002vm001vig001"
+              },
+              "attributes": {OPAQUE-DICT}
+            },
+            "DEMAND_NAME_2": {
+              "inventory_provider": "aai",
+              "service_resource_id": "578eb063-b24a-4654-ba9e-1e5cf7eb9183",
+              "candidate": {
+                "inventory_type": "cloud",
+                "location_type": "aic",
+                "location_id": "dal02"
+              },
+              "attributes": {OPAQUE-DICT}
+            }
+          },
+          {
+            "DEMAND_NAME_1": {
+              "inventory_provider": "aai",
+              "service_resource_id": "4feb0545-69e2-424c-b3c4-b270e5f2a15d",
+              "candidate": {
+                "candidate_id": "99befee8-e8c0-425b-8f36-fb7a8098d9a9",
+                "inventory_type": "service",
+                "location_type": "aic",
+                "location_id": "dal03",
+                "host_id" : "vig20001vm001vig001"
+              },
+              "attributes": {OPAQUE-DICT}
+            },
+            "DEMAND_NAME_2": {
+              "inventory_provider": "aai",
+              "service_resource_id": "578eb063-b24a-4654-ba9e-1e5cf7eb9183",
+              "candidate": {
+                "inventory_type": "cloud",
+                "location_type": "aic",
+                "location_id": "dal04"
+              },
+              "attributes": {OPAQUE-DICT}
+            }
+          },
+          ...
+        ]
+      }
+    }
+
+Show plan details
+-----------------
+
+**GET** ``/v1/plans/{plan_id}``
+
+-  **Normal response codes:** 200
+-  **Error response codes:** unauthorized (401), itemNotFound (404)
+
+Request parameters
+~~~~~~~~~~~~~~~~~~
+
++---------------+---------+--------------+-------------------------+
+| Parameter     | Style   | Type         | Description             |
++===============+=========+==============+=========================+
+| ``plan_id``   | plain   | csapi:UUID   | The UUID of the plan.   |
++---------------+---------+--------------+-------------------------+
+
+Response Parameters
+~~~~~~~~~~~~~~~~~~~
+
+See the Response Parameters for **Create a plan**.
+
+Delete a plan
+-------------
+
+**DELETE** ``/v1/plans/{plan_id}``
+
+-  **Normal response codes:** 204
+-  **Error response codes:** badRequest (400), unauthorized (401),
+   itemNotFound (404)
+
+Request parameters
+~~~~~~~~~~~~~~~~~~
+
++---------------+---------+--------------+-------------------------+
+| Parameter     | Style   | Type         | Description             |
++===============+=========+==============+=========================+
+| ``plan_id``   | plain   | csapi:UUID   | The UUID of the plan.   |
++---------------+---------+--------------+-------------------------+
+
+This operation does not accept a request body and does not return a
+response body.
+
+API Errors
+----------
+
+In the event of an error with a status other than unauthorized (401), a
+detailed repsonse body is returned.
+
+Response parameters
+~~~~~~~~~~~~~~~~~~~
+
++-----------------+--------+------------+---------------------------------------------+
+| Parameter       | Style  | Type       | Description                                 |
++=================+========+============+=============================================+
+| ``title``       | plain  | xsd:string | Human-readable name.                        |
++-----------------+--------+------------+---------------------------------------------+
+| ``explanation`` | plain  | xsd:string | Detailed explanation with remediation (if   |
+|                 |        |            | any).                                       |
++-----------------+--------+------------+---------------------------------------------+
+| ``code``        | plain  | xsd:int    | HTTP Status Code.                           |
++-----------------+--------+------------+---------------------------------------------+
+| ``error``       | plain  | xsd:dict   | Error dictionary. Keys include **message**, |
+|                 |        |            | **traceback**, and **type**.                |
++-----------------+--------+------------+---------------------------------------------+
+| ``message``     | plain  | xsd:string | Internal error message.                     |
++-----------------+--------+------------+---------------------------------------------+
+| ``traceback``   | plain  | xsd:string | Python traceback (if available).            |
+|                 |        |            |                                             |
++-----------------+--------+------------+---------------------------------------------+
+| ``type``        | plain  | xsd:string | HTTP Status class name (from python-webob)  |
++-----------------+--------+------------+---------------------------------------------+
+
+Examples
+^^^^^^^^
+
+A plan with the name "pl an" is considered a bad request because the
+name contains a space.
+
+.. code:: json
+
+    {
+      "title": "Bad Request",
+      "explanation": "-> name -> pl an did not pass validation against callable: plan_name_type (must contain only uppercase and lowercase letters, decimal digits, hyphens, periods, underscores, and tildes [RFC 3986, Section 2.3])",
+      "code": 400,
+      "error": {
+        "message": "The server could not comply with the request since it is either malformed or otherwise incorrect.",
+        "type": "HTTPBadRequest"
+      }
+    }
+
+The HTTP COPY method was attempted but is not allowed.
+
+.. code:: json
+
+    {
+      "title": "Method Not Allowed",
+      "explanation": "The COPY method is not allowed.",
+      "code": 405,
+      "error": {
+        "message": "The server could not comply with the request since it is either malformed or otherwise incorrect.",
+        "type": "HTTPMethodNotAllowed"
+      }
+    }