openstack/deb-murano
Code Issues Proposed changes

Updates environment api-ref.

Browse Source 
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
This commit is contained in:
Felipe Monteiro 2017-04-27 19:05:08 +01:00
parent ea4a304398
commit ed4a6b5ddc
8 changed files with 175 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/v1/deployments.inc
View File

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

84
api-ref/source/v1/environments.inc
View File

@ -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
- updated: updated
- networking: networking
- id: env_id
- 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
----------------

63
api-ref/source/v1/parameters.yaml
View File

@ -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
one non-white space symbol.
A name for the environment. Name must be at least one non-white space
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.

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

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

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

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

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

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

2
api-ref/source/v1/sessions.inc
View File

@ -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

8
api-ref/source/v1/templates.inc
View File

@ -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