Updates environment api-ref.

This patch makes the following changes to the environment api-ref:
  - Adds an environment overview
  - Removes 500 error codes (any endpoint can arguably throw a 500
    but a 500 is not an expected error code)
  - Adds additional status codes that can be returned by endpoints
  - Updates deprecated response bodies

Also adds X-Openstack-Request-Id to response parameters throughout
the murano api docs that are currently missing it.

Change-Id: I77f88a29639bae6612a46e800444e9b34485c2af

api-ref/source/v1/deployments.inc

@@ -40,6 +40,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+    - X-Openstack-Request-Id: request_id
     - deployments: deployments
 
 Response Example

api-ref/source/v1/environments.inc

@@ -4,6 +4,16 @@
 Environments
 ============
 
+An environment is a set of logically connected applications that are grouped
+together for easy management. By default, each environment has a single
+network for all its applications, and the deployment of the environment is
+defined in a single heat stack. Applications in different environments are
+always independent from one another.
+
+An environment is a single unit of deployment. This means that you can not only
+deploy an environment that contains a single application but an environment
+that contains multiple applications.
+
 List environments
 =================
 
@@ -20,9 +30,8 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
-   - 500
+   - 403
 
 Request Parameters
 ------------------
@@ -39,10 +48,10 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - environments: environments
    - status: env_status
-   - updated: updated
-   - networking: networking
-   - name: env_name
    - created: created
+   - updated: updated
+   - name: env_name
+   - description_text: env_description
    - tenant_id: tenant_id
    - version: env_version
    - id: env_id
@@ -71,6 +80,7 @@ Response Codes
 
    - 400
    - 401
+   - 403
    - 409
 
 Request Parameters
@@ -94,10 +104,13 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - id: env_id
    - name: env_name
+   - description_text: env_description
    - created: created
    - updated: updated
    - tenant_id: tenant_id
    - version: env_version
+   - services: services
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -105,33 +118,34 @@ Response Example
 .. literalinclude:: samples/environment-create-response.json
    :language: javascript
 
-Update environment
+Rename environment
 ==================
 
-.. rest_method::  PUT /environments/<env_id>
+.. rest_method::  PUT /environments/{env_id}
 
-Updates an environment.
+Renames an environment.
 
 Response Codes
 --------------
 
 .. rest_status_code:: success status.yaml
 
-   - 202
+   - 200
 
 .. rest_status_code:: error status.yaml
 
    - 400
+   - 401
    - 403
    - 404
    - 409
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
+   - env_id: env_id_url
    - name: env_name_update
 
 Request Example
@@ -148,10 +162,13 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - id: env_id
    - name: env_name
+   - description_text: env_description
    - created: created
    - updated: updated
    - tenant_id: tenant_id
    - version: env_version
+   - services: services
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -162,7 +179,7 @@ Response Example
 Show environment details
 ========================
 
-.. rest_method::  GET /environments/{id}
+.. rest_method::  GET /environments/{env_id}
 
 Shows details for a environment.
 
@@ -175,17 +192,16 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
+   - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
 
 Response Parameters
 -------------------
@@ -193,15 +209,15 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - X-Openstack-Request-Id: request_id
-   - status: env_status
+   - id: env_id
-   - updated: updated
-   - networking: networking
    - name: env_name
+   - description_text: env_description
    - created: created
+   - updated: updated
    - tenant_id: tenant_id
    - version: env_version
    - services: services
-   - id: env_id
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -212,7 +228,7 @@ Response Example
 Delete environment
 ==================
 
-.. rest_method::  DELETE /environments/{id}
+.. rest_method::  DELETE /environments/{env_id}
 
 Remove specified Environment.
 
@@ -225,16 +241,16 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
+   - 401
    - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
    - abandon: abandon
 
 Response Parameters
@@ -258,9 +274,9 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
-   - 500
+   - 403
+   - 404
 
 Request Parameters
 ------------------
@@ -278,8 +294,8 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - defaultNetworks: env_default_networks
    - region: env_region
-   - name: env_name
    - regions: regions
+   - name: env_name
    - services: services
    - ?: env_model
 
@@ -292,9 +308,9 @@ Response Example
 Update environment model
 ========================
 
-.. rest_method::  PATCH /environments/<env_id>/model/
+.. rest_method::  PATCH /environments/{env_id}/model/
 
-Update an Environment model.
+Update an environment model.
 
 Response Codes
 --------------
@@ -306,17 +322,17 @@ Response Codes
 .. rest_status_code:: error status.yaml
 
    - 400
+   - 401
    - 403
    - 404
    - 409
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - name: env_name_update
+   - env_id: env_id_url
 
 Request Example
 ---------------
@@ -332,8 +348,8 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - defaultNetworks: env_default_networks
    - region: env_region
-   - name: env_name
    - regions: regions
+   - name: env_name
    - services: services
    - ?: env_model
 
@@ -346,9 +362,9 @@ Response Example
 Get environment last status
 ===========================
 
-.. rest_method::  GET /environments/{id}/lastStatus
+.. rest_method::  GET /environments/{env_id}/lastStatus
 
-Get last status for a environment.
+Get the last status for the environment for each service in the environment.
 
 Response Codes
 --------------
@@ -361,15 +377,15 @@ Response Codes
 
    - 400
    - 401
+   - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
 
 Response Parameters
 -------------------
@@ -377,7 +393,7 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - X-Openstack-Request-Id: request_id
-   - uuid: last_status_uuid
+   - lastStatuses: env_last_status
 
 Response Example
 ----------------

api-ref/source/v1/parameters.yaml

@@ -79,6 +79,7 @@ template_is_public_url:
       are listed
   in: path
   required: false
+  default: false
   type: boolean
 
 # variables in query
@@ -184,6 +185,13 @@ search:
   type: string
 
 # variables in body
+acquired_by:
+  description: |
+    The session that is currently `deploying` the environment. Returns the
+    `first` session id that is in ``DEPLOYING`` state for the environment.
+  in: body
+  required: true
+  type: string
 all_categories:
   description: |
     All categories available in the application catalog.
@@ -265,26 +273,57 @@ enabled:
   type: boolean
 env_default_networks:
   description: |
-    The default networks of the environment.
+    The default networking information of the environment. The information
+    includes the ``name`` of the network, along with the ``type`` and ``id``
+    of the network, contained in the ``?`` property.
+
+    An example ``defaultNetworks`` object looks like::
+
+        "defaultNetworks": {
+            "environment": {
+                "internalNetworkName": "net_two",
+                "?": {
+                    "type": "io.murano.resources.ExistingNeutronNetwork",
+                    "id": "594e94fcfe4c48ef8f9b55edb3b9f177"
+                }
+            },
+            "flat": null
+        }
   in: body
   required: true
-  type: array
+  type: object
+env_description:
+  description: |
+    The description of the environment.
+  in: body
+  required: true
+  type: string
 env_id:
   description: |
     The UUID of the environment.
   in: body
   required: true
   type: string
-env_model:
+env_last_status:
   description: |
-    The ``?`` sections of the environment.
+    Shows the most recent status of the environment for each service in the
+    environment. The response object includes detailed information
+    by ``service_id``.
   in: body
   required: true
-  type: array
+  type: object
+env_model:
+  description: |
+    The ``?`` section of the environment, containing information about the
+    environment model, including its ``type``, ``id`` and associated
+    ``metadata``.
+  in: body
+  required: true
+  type: object
 env_name:
   description: |
-    A name for the environment. Name must be at least
+    A name for the environment. Name must be at least one non-white space
-    one non-white space symbol.
+    symbol and less than 256 characters long.
   in: body
   required: true
   type: string
@@ -341,12 +380,6 @@ is_public:
   in: body
   required: true
   type: boolean
-last_status_uuid:
-  description: |
-    A list of environment last status object.
-  in: body
-  required: true
-  type: array
 networking:
   description: |
     Current network of the environment.
@@ -409,10 +442,10 @@ pkg_type:
   type: string
 regions:
   description: |
-    The regions detail of the cloud.
+    Detailed region information for the cloud environment.
   in: body
   required: true
-  type: array
+  type: object
 services:
   description: |
     A list of ``service`` objects.

api-ref/source/v1/samples/environment-create-response.json

@@ -1,8 +1,12 @@
 {
-    "id": "ce373a477f211e187a55404a662f968",
+  "status": "ready",
-    "name": "env_name",
+  "updated": "2017-04-27T15:36:02",
-    "created": "2013-11-30T03:23:42Z",
+  "created": "2017-04-27T15:36:02",
-    "updated": "2013-11-30T03:23:44Z",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
-    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
+  "acquired_by": null,
-    "version": 0
+  "services": [],
+  "version": 0,
+  "description_text": "",
+  "id": "a2977db57398401aba5804ef2211a2a3",
+  "name": "env_name"
 }

api-ref/source/v1/samples/environment-show-response.json

@@ -1,11 +1,9 @@
 {
   "status": "ready",
-    "updated": "2014-05-14T13:12:26",
+  "updated": "2017-04-27T15:36:02",
-    "networking": {},
+  "created": "2017-04-27T15:36:02",
-    "name": "quick-env-2",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
-    "created": "2014-05-14T13:09:55",
+  "acquired_by": null,
-    "tenant_id": "726ed856965f43cc8e565bc991fa76c3",
-    "version": 1,
   "services": [
     {
         "instance": {
@@ -31,5 +29,8 @@
         }
     }
   ],
-    "id": "20d4a012628e4073b48490a336a8acbf"
+  "version": 0,
+  "description_text": "",
+  "id": "a2977db57398401aba5804ef2211a2a3",
+  "name": "env_name"
 }

api-ref/source/v1/samples/environment-update-response.json

@@ -1,8 +1,12 @@
 {
-    "id": "ce373a477f211e187a55404a662f968",
+  "status": "ready",
-    "name": "env_name_changed",
+  "updated": "2017-04-27T16:01:29",
-    "created": "2013-11-30T03:23:42Z",
+  "created": "2017-04-27T15:33:55",
-    "updated": "2013-11-30T03:45:54Z",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
-    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
+  "acquired_by": null,
-    "version": 0
+  "services": [],
+  "version": 0,
+  "description_text": "",
+  "id": "f199275420ff4e938e0307b0cf68374d",
+  "name": "env_name_changed"
 }

api-ref/source/v1/sessions.inc

@@ -49,6 +49,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - environment_id: env_id
@@ -121,6 +122,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - id: session_id
    - environment_id: env_id
    - created: created

api-ref/source/v1/templates.inc

@@ -83,6 +83,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - templates: templates
    - created: created
    - updated: updated
@@ -137,6 +138,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - name: template_name
@@ -183,6 +185,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - name: template_name
@@ -263,6 +266,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - updated: updated
    - created: created
    - tenant_id: tenant_id
@@ -336,6 +340,7 @@ Request Parameters
 Response Parameters
 -------------------
 
+   - X-Openstack-Request-Id: request_id
    - updated: updated
    - created: created
    - tenant_id: tenant_id
@@ -391,6 +396,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - service: template_service
 
 Response Example
@@ -438,6 +444,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - environment_id: env_id
    - name: env_name
    - created: created
@@ -495,6 +502,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - environment_id: env_id
    - name: env_name
    - created: created