Add /v1/plans api-ref

This patch set adds in /v1/plans API reference documentation.

Change-Id: Idb37986b464529a5ef500f443e23db189427a0d5

api-ref/source/v1/index.rst

@@ -1,13 +1,15 @@
 :tocdepth: 2
 
-=======================
+======================
- Valet API v1 (CURRENT)
+Valet API v1 (CURRENT)
-=======================
+======================
 
 This page lists the Valet API operations in the following order:
 
 * `Groups`_
+* `Plans`_
 
 .. rest_expand_all::
 
 .. include:: groups.inc
+.. include:: plans.inc

api-ref/source/v1/parameters.yaml

@@ -13,8 +13,27 @@ member_id_query:
   in: query
   required: true
   type: string
+plan_id_query:
+  description: |
+    The UUID of a plan
+  in: query
+  required: true
+  type: string
 
 # Parameters in body
+action:
+  description: |
+    The plan update action.  The only valid option is **migrate**, to
+    replan a single resource.
+  in: body
+  required: true
+  type: string
+excluded_hosts:
+  description: |
+    A list of hosts that must **not** be considered when replanning.
+  in: body
+  required: true
+  type: list
 group_description:
   description: |
     Description of a group.
@@ -48,3 +67,60 @@ group_type:
   in: body
   required: true
   type: string
+locations:
+  description: |
+    List of placement location candidates.
+  in: body
+  required: false
+  type: list
+placements:
+  description: |
+    Dictionary of planned resource.  Each is keyed by an orchestration UUID.
+    This is a UUID provided by an orchestration engine (e.g. heat-engine)
+    prior to instantiation of a resource.  The dictionary contains two keys,
+
+    - **location**: resource placement
+    - **name**: resource name
+
+  in: body
+  required: true
+  type: string
+plan_id:
+  description: |
+    UUID of the plan.
+  in: body
+  required: true
+  type: string
+plan_name:
+  description: |
+    Name of the plan.
+  in: body
+  required: true
+  type: string
+resources:
+  description: |
+    A dictionary of resources to be planned. Each is keyed by an orchestration
+    UUID. This is a UUID provided by an orchestration engine (e.g. heat-engine)
+    prior to instantiation of a resource.  The dictionary contains three keys,
+
+    - **name**: resource name
+    - **type**: resource type (in HOT format),
+    - **properties**: resource properties (in HOT format)
+
+  in: body
+  required: true
+  type: dictionary
+resources_update:
+  description: |
+    A list of resource IDs.  If the ``action`` is ``migrate``, this is a list
+    of a length one. The lone item is either a physical resource id or an
+    orchestration id.
+  in: body
+  required: true
+  type: list
+stack_id:
+  description: |
+    UUID of the stack.
+  in: body
+  required: true
+  type: string

api-ref/source/v1/plans.inc

@@ -0,0 +1,213 @@
+.. -*- rst -*-
+
+=====
+Plans
+=====
+
+Create a plan
+=============
+
+.. rest_method:: POST /v1/plans
+
+Creates a plan.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 201
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 401
+   - 500
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - locations: locations
+   - plan_name: plan_name
+   - resources: resources
+   - stack_id: stack_id
+
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/create_plan_request.json
+   :language: json
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_id: stack_id
+   - placements: placements
+   - id: plan_id
+   - name: plan_name
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/create_plan_response.json
+   :language: json
+
+List active plans
+=================
+
+.. rest_method:: GET /v1/plans
+
+Lists all plans.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 401
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_id: stack_id
+   - placements: placements
+   - id: plan_id
+   - name: plan_name
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/list_plan_response.json
+   :language: json
+
+Show plan details
+=================
+
+.. rest_method:: GET /v1/plans/{plan_id}
+
+Lists all plans.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../status.yaml
+
+   - 401
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - plan_id: plan_id_query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_id: stack_id
+   - placements: placements
+   - id: plan_id
+   - name: plan_name
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/show_plan_response.json
+   :language: json
+
+
+Update a plan
+=============
+
+.. rest_method:: PUT /v1/plans/{plan_id}
+
+Update a plan.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 201
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 401
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - plan_id: plan_id_query
+   - action: action
+   - excluded_hosts: excluded_hosts
+   - resources: resources_update
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/update_plan_request.json
+   :language: json
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_id: stack_id
+   - id: plan_id
+   - placements: placements
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/update_plan_response.json
+   :language: json
+
+Delete a plan
+=============
+
+.. rest_method:: DELETE /v1/plans/{plan_id}
+
+Deletes a plan.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 204
+
+.. rest_status_code:: error ../status.yaml
+
+   - 400
+   - 401
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - plan_id: plan_id_query

api-ref/source/v1/samples/create_plan_request.json

@@ -0,0 +1,20 @@
+{
+  "plan_name": "e624474b-fc80-4053-ab5f-45cc1030e692",
+  "resources": {
+    "b71bedad-dd57-4942-a7bd-ab074b72d652": {
+      "properties": {
+        "flavor": "m1.small",
+        "image": "ubuntu12_04",
+        "key_name": "demo",
+        "networks": [
+          {
+            "network": "demo-net"
+          }
+        ]
+      },
+      "type": "OS::Nova::Server",
+      "name": "my_instance"
+    }
+  },
+  "stack_id": "e624474b-fc80-4053-ab5f-45cc1030e692"
+}

api-ref/source/v1/samples/create_plan_response.json

@@ -0,0 +1,13 @@
+{
+  "plan" {
+    "stack_id": "e624474b-fc80-4053-ab5f-45cc1030e692",
+    "id": "1853a7e7-0075-465b-9019-8908db680f2e",
+    "placements": {
+      "b71bedad-dd57-4942-a7bd-ab074b72d652": {
+        "location": "qos103",
+        "name": "my_instance"
+      }
+    },
+    "name": "e624474b-fc80-4053-ab5f-45cc1030e692"
+  }
+}

api-ref/source/v1/samples/list_plan_response.json

@@ -0,0 +1,26 @@
+{
+  "plans": [
+    {
+      "stack_id": "e624474b-fc80-4053-ab5f-45cc1030e692",
+      "id": "f1a81397-e4d4-46de-8445-dfadef633beb",
+      "placements": {
+        "b71bedad-dd57-4942-a7bd-ab074b72d652": {
+          "location": "qos101",
+          "name": "my_instance"
+        }
+      },
+      "name": "e624474b-fc80-4053-ab5f-45cc1030e692"
+    },
+    {
+      "stack_id": "8e06301e-7375-465f-9fc7-70fb13763927",
+      "id": "f56391b0-61bb-4e18-b9ca-23c0ff2e4508",
+      "placements": {
+        "8e06301e-7375-465f-9fc7-70fb13763927": {
+          "location": "qos101",
+          "name": "ad_hoc_instance"
+        }
+      },
+      "name": "8e06301e-7375-465f-9fc7-70fb13763927"
+    }
+  ]
+}

api-ref/source/v1/samples/show_plan_response.json

@@ -0,0 +1,13 @@
+{
+  "plan": {
+    "stack_id": "e624474b-fc80-4053-ab5f-45cc1030e692",
+    "id": "1853a7e7-0075-465b-9019-8908db680f2e",
+    "placements": {
+      "b71bedad-dd57-4942-a7bd-ab074b72d652": {
+        "location": "qos103",
+        "name": "my_instance"
+      }
+    },
+    "name": "e624474b-fc80-4053-ab5f-45cc1030e692"
+  }
+}

api-ref/source/v1/samples/update_plan_request.json

@@ -0,0 +1,5 @@
+{
+  "action": "migrate",
+  "excluded_hosts": ["qos104", "qos106", "qos107"],
+  "resources": ["b71bedad-dd57-4942-a7bd-ab074b72d652"]
+}

api-ref/source/v1/samples/update_plan_response.json

@@ -0,0 +1,13 @@
+{
+  "plan": {
+    "stack_id": "e624474b-fc80-4053-ab5f-45cc1030e692",
+    "id": "a78d1936-0b63-4ce3-9450-832f71ebf160",
+    "placements": {
+      "b71bedad-dd57-4942-a7bd-ab074b72d652": {
+        "location": "qos105",
+        "name": "my_instance"
+      }
+    },
+    "name": "e624474b-fc80-4053-ab5f-45cc1030e692"
+  }
+}