Add deployments to api-ref

This patch adds the deployments api to api-ref.

Change-Id: If5042f558cf755a738a67daba8e1fe4d6dad055f
Partially-Implements: blueprint murano-api-ref

api-ref/source/v1/deployments.inc

@@ -0,0 +1,49 @@
+.. -*- rst -*-
+
+===========
+Deployments
+===========
+
+Deployments track environments that have been deployed, either successfully
+or otherwise. Each deployment contains the following information:
+
+* A "Class: Environment" object (io.murano.Environment) with a name. Each
+  "Class: Environment" object defines an environment in terms of the deployment
+  process and groups all Applications and their related infrastructures together.
+* An object (or objects) referring to networks that exist.
+* A list of Applications (e.g. io.murano.apps.linux.Telnet). Each Application
+  contains, or otherwise references, anything it requires. The Telnet example
+  has a property called ``instance`` whose contract states it must be of type
+  ``io.murano.resources.Instance``. In turn, the Instance has properties it
+  requires (like a ``name``, a ``flavor``, or a keypair name, ``keyname``).
+
+List deployments
+================
+
+.. rest_method::  GET /deployments
+
+List deployments for all environments for the current tenant (project).
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - deployments: deployments
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployments-list-response.json
+   :language: javascript

api-ref/source/v1/index.rst

@@ -7,6 +7,7 @@ OpenStack Application Catalog API v1
 .. rest_expand_all::
 
 .. include:: categories.inc
+.. include:: deployments.inc
 .. include:: environments.inc
 .. include:: packages.inc
 .. include:: sessions.inc

api-ref/source/v1/parameters.yaml

@@ -212,6 +212,20 @@ created:
   in: body
   required: true
   type: string
+deployments:
+  description: |
+    The list of deployments for either the current environment or all
+    environments for the current tenant (project).
+
+    The following APIs control whether deployments by environment or by
+    project are returned:
+
+    * ``/deployments``: Returns all deployments for a project.
+    * ``/environments/{env_id}/deployments``: Returns all deployments for an
+      environment in a project.
+  in: body
+  required: true
+  type: array
 description:
   description: |
     The description of the package.
@@ -264,7 +278,17 @@ env_region:
   type: string
 env_status:
   description: |
-    Current status of the environment.
+    Current status of the environment. The available statuses are:
+
+    * **Ready to configure**. When the environment is new and contains no
+      components.
+    * **Ready to deploy**. When the environment contains a component or multiple
+      components and is ready for deployment.
+    * **Ready**. When the environment has been successfully deployed.
+    * **Deploying**. When the deploying is in progress.
+    * **Deploy FAILURE**. When the deployment finished with errors.
+    * **Deleting**. When deleting of an environment is in progress.
+    * **Delete FAILURE**. You can abandon the environment in this case.
   in: body
   required: true
   type: string

api-ref/source/v1/samples/deployments-list-response.json

@@ -0,0 +1,51 @@
+{
+    "deployments": [
+        {
+            "updated": "2014-05-15T07:24:21",
+            "environment_id": "744e44812da84e858946f5d817de4f72",
+            "description": {
+                "services": [
+                    {
+                        "instance": {
+                            "flavor": "m1.medium",
+                            "image": "cloud-fedora-v3",
+                            "?": {
+                                "type": "io.murano.resources.Instance",
+                                "id": "ef729199-c71e-4a4c-a314-0340e279add8"
+                            },
+                            "name": "xkaduhv7qeg4m7"
+                        },
+                        "name": "teslnet1",
+                        "?": {
+                            "_26411a1861294160833743e45d0eaad9": {
+                                "name": "Telnet"
+                            },
+                            "type": "io.murano.apps.linux.Telnet",
+                            "id": "6e437be2-b5bc-4263-8814-6fd57d6ddbd5"
+                        }
+                    }
+                ],
+                "defaultNetworks": {
+                    "environment": {
+                        "name": "test2-network",
+                        "?": {
+                            "type": "io.murano.lib.networks.neutron.NewNetwork",
+                            "id": "b6a1d515434047d5b4678a803646d556"
+                        }
+                    },
+                    "flat": null
+                },
+                "name": "test2",
+                "?": {
+                    "type": "io.murano.Environment",
+                    "id": "744e44812da84e858946f5d817de4f72"
+                }
+            },
+            "created": "2014-05-15T07:24:21",
+            "started": "2014-05-15T07:24:21",
+            "finished": null,
+            "state": "running",
+            "id": "327c81e0e34a4c93ad9b9052ef42b752"
+        }
+    ]
+}