openstack/heat
Code Issues Proposed changes

api-ref - stack actions

Browse Source 
This patch fixes problems found in api-ref documentation related
to stack actions and missing stack APIs. More specifically, this
include the following changes:

- Fix status code documentation about stack actions;
- Added response parameters for some actions although there is no
  body returned -- there are still header returned;
- Added documentation about stack-export API;
- Added documentation about stack-environment-show API;
- Added documentation about stack-files-show API;

Change-Id: I8b2266ec7a7a22fc1cb1782e98beac315e054013
This commit is contained in:
tengqm 2016-08-21 22:14:54 -04:00 committed by Qiming Teng
parent 50f38415da
commit 623c5a5354
7 changed files with 355 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -380,6 +380,12 @@ with_detail:
type: boolean
# variables in body
action:
description: |
The last action executed on the stack.
in: body
required: true
type: string
adopt_stack_data:
description: |
Existing resources data to adopt a stack. Data returned by abandon
@ -615,6 +621,12 @@ disable_rollback:
required: false
default: True
type: boolean
encrypted_param_names:
description: |
A list of parameter names whose values are encrypted.
in: body
required: true
type: array
engine_id:
description: |
The UUID of the engine service.
@ -667,6 +679,12 @@ event_links:
in: body
required: true
type: array
event_sinks:
description: |
A list of event sinks.
in: body
required: true
type: array
event_time:
description: |
The date and time when the event was created. The date and time stamp
@ -910,6 +928,12 @@ outputs:
in: body
required: false
type: array
parameter_defaults:
description: |
A map of parameters and their default values defined for the stack.
in: body
required: true
type: object
ParameterGroups:
description: |
A list of parameter groups. Each group contains a
@ -1000,6 +1024,12 @@ parameters:
in: body
required: false
type: object
parameters_show:
description: |
A map of parameters defined for the stack.
in: body
required: true
type: object
parent:
description: |
The stack ID of the parent stack, if this is a nested stack.
@ -1112,6 +1142,13 @@ resource_properties:
in: body
required: true
type: object
resource_registry:
description: |
A map containing customized resource definitions. This map contains at
least a dict of ``resources`` registered for the stack.
in: body
required: true
type: object
resource_status:
description: |
The status of the resource.
@ -1433,8 +1470,7 @@ support_status:
type: object
suspend:
description: |
Specify the ``suspend`` action in the request
body.
Specify the ``suspend`` action in the request body.
in: body
required: true
type: string

4
api-ref/source/v1/resources.inc
View File

@ -260,8 +260,8 @@ Response Example
This operation does not return a response body.
Mark a resource unhealthy
===========================
Mark a resource as unhealthy
============================
.. rest_method:: PATCH /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}

9
api-ref/source/v1/samples/stack-environment-show-response.json Normal file
View File

@ -0,0 +1,9 @@
{
"encrypted_param_names": [],
"event_sinks": [],
"parameter_defaults": {},
"parameters": {},
"resource_registry": {
"resources": {}
}
}

60
api-ref/source/v1/samples/stack-export-response.json Normal file
View File

@ -0,0 +1,60 @@
{
"action": "SUSPEND",
"environment": {
"event_sinks": [],
"parameter_defaults": {},
"parameters": {},
"resource_registry": {
"resources": {}
}
},
"files": {},
"id": "da778f26-6d25-4634-9531-d438188e48fd",
"name": "s1",
"project_id": "369166a68a3a49b78b4e138531556e55",
"resources": {
"random": {
"action": "SUSPEND",
"metadata": {},
"name": "random",
"resource_data": {
"value": "wCPWWoGJH5SZKtNFAgqGcbiWokCkRgam"
},
"resource_id": "s1-random-pzuzs6pbjhho",
"status": "COMPLETE",
"type": "OS::Heat::RandomString"
}
},
"stack_user_project_id": "a4e6fd443f5b4d4694331ff441ad2397",
"status": "COMPLETE",
"tags": null,
"template": {
"heat_template_version": "2014-10-16",
"outputs": {
"result": {
"value": {
"get_attr": [
"random",
"value"
]
}
}
},
"parameters": {
"str_length": {
"default": 32,
"type": "number"
}
},
"resources": {
"random": {
"properties": {
"length": {
"get_param": "str_length"
}
},
"type": "OS::Heat::RandomString"
}
}
}
}

3
api-ref/source/v1/samples/stack-files-show-response.json Normal file
View File

@ -0,0 +1,3 @@
{
"file:///home/username/hello.sh": "#!/bin/sh\necho hello\n"
}

112
api-ref/source/v1/stack-actions.inc
View File

@ -4,8 +4,8 @@
Stack actions
=============
Performs non-lifecycle operations on the stack. Specify the action
in the request body.
Performs non-lifecycle operations on the stack. Specify the action in the
request body.
Suspend stack
=============
@ -14,17 +14,27 @@ Suspend stack
Suspends a stack.
Normal response codes: 200
Error response codes:
Response Codes
--------------
Request
-------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- stack_id: stack_id_url
- suspend: suspend
Request Example
@ -33,6 +43,13 @@ Request Example
.. literalinclude:: samples/stack-action-suspend-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Response Example
----------------
@ -46,17 +63,27 @@ Resume stack
Resumes a suspended stack.
Normal response codes: 200
Error response codes:
Response Codes
--------------
Request
-------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- stack_id: stack_id_url
- resume: resume
Request Example
@ -65,6 +92,13 @@ Request Example
.. literalinclude:: samples/stack-action-resume-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Response Example
----------------
@ -78,17 +112,27 @@ Cancel stack update
Cancels a currently running update of a stack.
Normal response codes: 200
Error response codes:
Response Codes
--------------
Request
-------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- stack_id: stack_id_url
- cancel_update: cancel_update
Request Example
@ -97,6 +141,13 @@ Request Example
.. literalinclude:: samples/stack-action-cancel-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Response Example
----------------
@ -110,17 +161,27 @@ Check stack resources
Checks whether the resources are in expected states for a stack.
Normal response codes: 200
Error response codes:
Response Codes
--------------
Request
-------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- stack_id: stack_id_url
- check: check
Request Example
@ -129,6 +190,13 @@ Request Example
.. literalinclude:: samples/stack-action-check-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Response Example
----------------

153
api-ref/source/v1/stacks.inc
View File

@ -676,6 +676,64 @@ Response Example
:language: javascript
Export stack
============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/export
Gets the stack data in JSON format.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 409
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
The body of the response contains a map of file names and file contents.
.. rest_parameters:: parameters.yaml
- X-Openstack-Reqeuest-Id: request_id
- action: action
- environment: stack_environment
- files: stack_files
- id: stack_id
- name: stack_name
- project_id: project_id
- resources: resources
- stack_user_project_id: stack_stack_user_project_id
- status: stack_status
- tags: stack_tags
- template: stack_template
Response Example
----------------
.. literalinclude:: samples/stack-export-response.json
:language: javascript
Get stack template
==================
@ -723,3 +781,98 @@ Response Example
.. literalinclude:: samples/template-show-response.json
:language: javascript
Get stack environment
=====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/environment
Gets the environment for a stack.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Reqeuest-Id: request_id
- encrypted_param_names: encrypted_param_names
- event_sinks: event_sinks
- parameter_defaults: parameter_defaults
- parameters: parameters
- resource_registry: resource_registry
Response Example
----------------
.. literalinclude:: samples/stack-environment-show-response.json
:language: javascript
Get stack files
===============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/files
Gets the files associated with a stack.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
The body of the response contains a map of file names and file contents.
.. rest_parameters:: parameters.yaml
- X-Openstack-Reqeuest-Id: request_id
Response Example
----------------
.. literalinclude:: samples/stack-files-show-response.json
:language: javascript