openstack/heat
Code Issues Proposed changes

api-ref doc for stack (1)

Browse Source 
This patch, as a first step, fixes inaccuracies/bugs in api-ref
documentation for stacks. The major changes in this patch include:

- Added missing 'location' and 'X-OpenStack-Request-Id' parameters
  which both appear in some response headers.
- Deleted some descriptions about parameters that are never
  referenced in any APIs.
- Added missing 'deletion_time' parameter.
- Added missing 'environment_files' parameter.
- Added missing sample JSON file for stack-create-response.json.
- Fixed errors in stack-preview-response.json.
- Added tabular description of response codes.
- Added a status.yaml file for response code description (shared).

Change-Id: I826ed899f925812df9b44144469700453789e087
This commit is contained in:
tengqm 2016-08-18 05:01:01 -04:00
parent 77927765a9
commit fa39e4b1fd
4 changed files with 238 additions and 407 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,4 +1,18 @@
# variables in header
location:
type: string
in: header
required: True
description: |
For asynchronous resource operations, the ``location`` header contains a
URI that can be checked to track resource status changes.
request_id:
type: UUID
in: header
description: |
A unique ID for tracking service request. The request ID associated
with the request by default appears in the service logs.
# variables in path
config_id_url:
@ -45,13 +59,13 @@ snapshot_id:
in: path
required: false
type: string
stack_id:
stack_id_url:
description: |
The UUID of the stack.
in: path
required: false
type: string
stack_name:
stack_name_url:
description: |
The name of a stack.
in: path
@ -66,9 +80,9 @@ template_version:
tenant_id:
description: |
The UUID of the tenant. A tenant is also known as
an account or project.
a project.
in: path
required: false
required: True
type: string
type_name:
description: |
@ -355,8 +369,7 @@ ParameterGroups:
type: array
Parameters:
description: |
Key and value pairs that contain template
parameters.
Key and value pairs that contain template parameters.
in: body
required: true
type: object
@ -474,100 +487,8 @@ created_at:
type: string
creation_time:
description: |
The date and time when the stack resource was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
creation_time_1:
description: |
The date and time when the software was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
creation_time_2:
description: |
The date and time when the resource was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
creation_time_3:
description: |
The date and time when the snapshot was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
creation_time_4:
description: |
The date and time when the software was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2016-03-30T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
creation_time_5:
description: |
The date and time when the stack was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
The date and time when the resource was created. The date and time stamp
format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
@ -604,6 +525,21 @@ deleted_at:
in: body
required: true
type: string
deletion_time:
description: |
The date and time when the resource was (soft-) deleted. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset from UTC.
in: body
required: true
type: string
deployment_action:
description: |
The stack action that triggers this deployment resource.
@ -672,73 +608,18 @@ deployment_updated_time:
type: string
description:
description: |
The description of the stack resource.
in: body
required: true
type: string
description_1:
description: |
The description of the resource attribute.
in: body
required: true
type: string
description_2:
description: |
The description of a stack output.
in: body
required: true
type: string
description_3:
description: |
The description of the active stack.
in: body
required: true
type: string
description_4:
description: |
A description of the stack.
in: body
required: true
type: string
description_5:
description: |
The description of the stack.
in: body
required: true
type: string
description_6:
description: |
The description of the stack template.
The description of the resource.
in: body
required: true
type: string
disable_rollback:
description: |
Enables or disables deletion of all stack
resources when stack creation fails. Set to ``true`` to keep all
resources when stack creation fails. Set to ``false`` to delete
all resources when stack creation fails. Default is ``true``.
Enables or disables deletion of all stack resources when stack creation
fails. Set to ``true`` to keep all resources when stack creation fails.
Set to ``false`` to delete all resources when stack creation fails.
in: body
required: false
type: boolean
disable_rollback_1:
description: |
Enables or disables deletion of all previously-
created stack resources when stack creation fails. Set to ``true``
to keep all previously-created stack resources when stack creation
fails. Set to ``false`` to delete all previously-created stack
resources when stack creation fails. Default is ``true``.
in: body
required: false
type: boolean
disable_rollback_2:
description: |
Enables or disables stack rollback when stack
creation fails. Set to ``true`` to rollback the stack when stack
creation fails. Set to ``false`` to disable stack rollback when
stack creation fails. Default is ``true``.
in: body
required: true
default: True
type: boolean
engine_id:
description: |
@ -752,6 +633,12 @@ environment:
in: body
required: false
type: object
environment_files:
description: |
An ordered list of names for environment files found in the ``files`` dict.
in: body
required: false
type: object
files:
description: |
Supplies the contents of files referenced in the template or the
@ -859,12 +746,6 @@ id_3:
in: body
required: true
type: string
id_5:
description: |
The UUID of the stack.
in: body
required: true
type: string
input_values:
description: |
A dict comprises of input data as key-value pairs.
@ -886,17 +767,10 @@ inputs_1:
type: array
links:
description: |
A list of URLs for the stack. Each URL is a JSON
object with an ``href`` key indicating the URL and a ``rel`` key
indicating its relationship to the stack in question. There may be
multiple links returned. The ``self`` relationship identifies the
URL of the stack itself.
in: body
required: true
type: array
links_1:
description: |
A list of stack links.
A list of URLs for the stack. Each URL is a JSON object with an ``href``
key indicating the URL and a ``rel`` key indicating its relationship to
the stack in question. There may be multiple links returned. The ``self``
relationship identifies the URL of the stack itself.
in: body
required: true
type: array
@ -975,12 +849,6 @@ outputs_1:
in: body
required: true
type: array
outputs_2:
description: |
A list of stack outputs.
in: body
required: true
type: array
outputs_3:
description: |
Key and value pairs that contain output data.
@ -1064,72 +932,9 @@ parameters:
in: body
required: false
type: object
parameters_1:
description: |
Key and value pairs that contain stack
parameters.
in: body
required: true
type: object
parameters_2:
description: |
Key and value pairs that contain template
parameters.
in: body
required: true
type: object
parameters_3:
description: "Supplies updated arguments for parameters that are defined in the\n\
stack template.\n\nThe value is a JSON object, where each key is the name of a\n\
parameter defined in the template and the associated value is the\nargument to\
\ use for that parameter when instantiating the template.\nThe following code\
\ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\
\ are the names of two parameters\ndefined in the template.\n\n.. code-block::\
\ json\n\n { ...\n \"parameters\": {\n \
\ \"a\": \"Value\",\n \"b\": \"3\"\n \
\ }\n ... }\n \n\
\nWhile the service accepts JSON numbers for parameters with the type\n``number``\
\ and JSON objects for parameters with the type ``json``,\nall parameter values\
\ are converted to their string representation\nfor storage in the created Stack.\
\ Clients are encouraged to send\nall parameter values using their string representation\
\ for\nconsistency between requests and responses from the Orchestration\nservice.\n\
\nYou must specify a value for each template parameter that does not\nhave a default\
\ value. However, this parameter cannot contain JSON\nproperties with names that\
\ do not match a parameter that is defined\nin the template.\n"
in: body
required: false
type: object
parameters_4:
description: "This parameter supplies updated arguments for parameters defined in\n\
the stack template.\n\nThe value is a JSON object, where each key is the name\
\ of a\nparameter defined in the template and the associated value is the\nargument\
\ to use for that parameter when instantiating the template.\nThe following code\
\ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\
\ are the names of two parameters\ndefined in the template.\n\n.. code-block::\
\ json\n\n { ...\n \"parameters\": {\n \
\ \"a\": \"Value\",\n \"b\": \"3\"\n \
\ }\n ... }\n \n\nWhile\
\ the service accepts JSON numbers for parameters with the type\n``number`` and\
\ JSON objects for parameters with the type ``json``,\nall parameter values are\
\ converted to their string representation\nfor storage in the created Stack.\
\ Clients are encouraged to send\nall parameter values using their string representation\
\ for\nconsistency between requests and responses from the Orchestration\nservice.\n\
\nYou must specify a value for each template parameter that does not\nhave a default\
\ value. However, this parameter cannot contain JSON\nproperties with names that\
\ do not match a parameter that is defined\nin the template.\n"
in: body
required: false
type: object
parent:
description: |
The stack ID of the parent stack, if this is a
nested stack.
in: body
required: true
type: string
parent_1:
description: |
The parent of the stack.
The stack ID of the parent stack, if this is a nested stack.
in: body
required: true
type: string
@ -1215,12 +1020,6 @@ resources:
in: body
required: true
type: array
resources_1:
description: |
List of stack resources.
in: body
required: true
type: array
resources_2:
description: |
The snapshot resources.
@ -1297,45 +1096,52 @@ stack:
in: body
required: true
type: object
stack_name_1:
stack_id:
description: |
A name for the new stack. The value must be
unique within a project. The name must start with an ASCII letter
and can contain ASCII letters, digits, underscores, periods, and
hyphens. Specifically, the name must match the
``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete
or abandon a stack, its name will not become available for reuse
until the deletion completes successfully.
The UUID of the stack.
in: body
required: true
type: string
stack_name_2:
stack_name:
description: |
A name for the new stack. This value must be
unique within a project. The name must start with an ASCII letter
and can contain ASCII letters, digits, underscores, periods, and
hyphens. Specifically, the name must match the
``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete
or abandon a stack, its name will not become available for reuse
until the deletion completes successfully.
A name for the stack. The value must be unique within a project.
The name must start with an ASCII letter and can contain ASCII letters,
digits, underscores, periods, and hyphens. Specifically, the name must
match the ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression.
When you delete or abandon a stack, its name will not become available
for reuse until the deletion completes successfully.
in: body
required: true
type: string
stack_name_3:
stack_outputs:
description: |
The name of the active stack.
A list of stack outputs.
in: body
required: true
type: string
type: array
stack_owner:
description: |
Stack owner name.
The owner of the stack
in: body
required: true
type: string
stack_owner_1:
stack_parameters:
description: |
The owner of the stack.
A group of key-value pairs where each key contains either a user-provided
parameter name or a built-in parameter name (e.g. ``OS::project_id``).
in: body
required: true
type: object
stack_resources:
description: |
List of stack resources.
in: body
required: true
type: array
stack_stack_user_project_id:
description: |
The project UUID of the stack user.
in: body
required: true
type: string
@ -1357,6 +1163,18 @@ stack_status_reason:
in: body
required: true
type: string
stack_tags:
description: |
The stack tags.
in: body
required: true
type: string
stack_timeout_mins:
description: |
The timeout for stack creation in minutes.
in: body
required: true
type: integer
stack_user_project_id:
description: |
Authentication project ID, which can also perform
@ -1364,12 +1182,6 @@ stack_user_project_id:
in: body
required: false
type: string
stack_user_project_id_1:
description: |
The project UUID of the stack user.
in: body
required: true
type: string
status:
description: |
The status of the heat engine.
@ -1410,72 +1222,34 @@ suspend:
type: string
tags:
description: |
One or more simple string tags to associate with
the stack. To associate multiple tags with a stack, separate the
tags with commas. For example, ``tag1,tag2``.
One or more simple string tags to associate with the stack. To associate
multiple tags with a stack, separate the tags with commas.
For example, ``tag1,tag2``.
in: body
required: false
type: string
tags_2:
description: |
The stack tags.
in: body
required: true
type: string
template:
description: |
The stack template on which to perform the operation.
This parameter is always provided as a ``string`` in the JSON
request body. The content of the string is a JSON- or YAML-
formatted Orchestration template. For example:
This parameter is always provided as a ``string`` in the JSON request body.
The content of the string is a JSON- or YAML-formatted Orchestration
template. For example:
.. code-block:: json
"template": {
"heat_template_version": "2013-05-23",
...}
...
}
This parameter is required only when you omit the ``template_url``
parameter. If you specify both parameters, this value overrides the
``template_url`` parameter value.
in: body
required: true
type: object
template_1:
description: |
Information about the template.
in: body
required: true
type: object
template_2:
description: |
The stack template on which to perform the operation.
This parameter is always provided as a ``string`` in the JSON
request body. The content of the string is a JSON- or YAML-
formatted Orchestration template. For example:
.. code-block:: json
"template": {
"heat_template_version": "2013-05-23",
...}
This parameter is required only when you omit the ``template_url``
parameter. If you specify both parameters, this value overrides the
``template_url`` parameter value.
in: body
required: false
required: False
type: object
template_description:
description: |
A description of the template that defines the
stack.
in: body
required: true
type: string
template_description_1:
description: |
The description of the stack template.
in: body
@ -1483,12 +1257,11 @@ template_description_1:
type: string
template_url:
description: |
A URI to the location containing the stack
template on which to perform the operation. See the description
of the ``template`` parameter for information about the expected
template content located at the URI. This parameter is only
required when you omit the ``template`` parameter. If you specify
both parameters, this parameter is ignored.
A URI to the location containing the stack template on which to perform
the operation. See the description of the ``template`` parameter for
information about the expected template content located at the URI.
This parameter is only required when you omit the ``template`` parameter.
If you specify both parameters, this parameter is ignored.
in: body
required: false
type: string
@ -1498,18 +1271,6 @@ timeout_mins:
in: body
required: false
type: integer
timeout_mins_1:
description: |
Time-lines for stack creation.
in: body
required: true
type: integer
timeout_mins_2:
description: |
The timeout, in minutes.
in: body
required: true
type: string
topic:
description: |
The topic of the heat engine.
@ -1551,10 +1312,8 @@ updated_at:
type: string
updated_time:
description: |
The date and time when the stack resource was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
The date and time when the object was updated. The date and time stamp
format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
@ -1562,32 +1321,7 @@ updated_time:
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: true
type: string
updated_time_1:
description: |
The date and time when the stack resource was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2016-03-30T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
The ``±hh:mm`` value, if included, is the time zone as an offset from UTC.
in: body
required: true
type: string

5
api-ref/source/v1/samples/stack-preview-response.json
View File

@ -2,6 +2,7 @@
"stack": {
"capabilities": [],
"creation_time": "2015-01-31T15:12:36Z",
"deletion_time": null,
"description": "HOT template for Nova Server resource.\n",
"disable_rollback": true,
"id": "None",
@ -12,6 +13,7 @@
}
],
"notification_topics": [],
"outputs": [],
"parameters": {
"OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804",
"OS::stack_id": "None",
@ -160,7 +162,8 @@
}
],
"stack_name": "test_stack",
"stack_owner": "admin",
"stack_owner": null,
"tags": null,
"template_description": "HOT template for Nova Server resource.\n",
"timeout_mins": null,
"updated_time": null

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

@ -11,23 +11,34 @@ Create stack
Creates a stack.
Error response codes:201,500,409,401,400,
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 201
.. rest_status_code:: error status.yaml
- 400
- 401
- 409
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- files: files
- disable_rollback: disable_rollback
- parameters: parameters
- tags: tags
- stack_name: stack_name
- environment: environment
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- tenant_id: tenant_id
- disable_rollback: disable_rollback
- environment: environment
- files: files
- parameters: parameters
- stack_name: stack_name
- tags: tags
- template: template
- template_url: template_url
- timeout_mins: timeout_mins
Request Example
---------------
@ -40,9 +51,17 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- location: location
- X-Openstack-Reqeuest-Id: request_id
- stack: stack
- id: id
- links: links
- stack: stack
Response Example
----------------
.. literalinclude:: samples/stack-create-response.json
:language: javascript
Preview stack
@ -52,20 +71,35 @@ Preview stack
Previews a stack.
Normal response codes: 200
Error response codes:500,409,401,400,
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 409
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- files: files
- stack_name: stack_name
- template_url: template_url
- template: template
- parameters: parameters
- tenant_id: tenant_id
- disable_rollback: disable_rollback
- environment: environment
- files: files
- parameters: parameters
- stack_name: stack_name
- tags: tags
- template: template
- template_url: template_url
- timeout_mins: timeout_mins
Request Example
---------------
@ -78,22 +112,27 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- parent: parent
- disable_rollback: disable_rollback
- description: description
- links: links
- stack_name: stack_name
- timeout_mins: timeout_mins
- creation_time: creation_time
- X-Openstack-Reqeuest-Id: request_id
- capabilities: capabilities
- creation_time: creation_time
- deletion_time: deletion_time
- description: description
- disable_rollback: disable_rollback
- id: stack_id
- links: links
- notification_topics: notification_topics
- updated_time: updated_time
- stack_owner: stack_owner
- stack: stack
- parameters: parameters
- id: id
- outputs: stack_outputs
- parameters: stack_parameters
- parent: parent
- resources: resources
- stack: stack
- stack_name: stack_name
- stack_owner: stack_owner
- stack_user_project_id: stack_stack_user_project_id
- tags: stack_tags
- template_description: template_description
- timeout_mins: timeout_mins
- updated_time: updated_time
Response Example
----------------

55
api-ref/source/v1/status.yaml Normal file
View File

@ -0,0 +1,55 @@
#################
# Success Codes #
#################
200:
default: |
Request was successful.
201:
default: |
Resource was created and is ready to use.
202:
default: |
Request was accepted for processing, but the processing has not been
completed. A 'location' header is included in the response which contains
a link to check the progress of the request.
204:
default: |
The server has fulfilled the request by deleting the resource.
300:
default: |
There are multiple choices for resources. The request has to be more
specific to successfully retrieve one of these resources.
#################
# Error Codes #
#################
400:
default: |
Some content in the request was invalid.
401:
default: |
User must authenticate before making a request.
403:
default: |
Policy does not allow current user to do this operation.
404:
default: |
The requested resource could not be found.
405:
default: |
Method is not valid for this endpoint.
409:
default: |
This operation conflicted with another operation on this resource.
duplcate_zone: |
There is already a zone with this name.
500:
default: |
Something went wrong inside the service. This should not happen usually.
If it does happen, it means the server has experienced some serious
problems.
503:
default: |
Service is not available. This is mostly caused by service configuration
errors which prevents the service from successful start up.