openstack/heat
Code Issues Proposed changes

api-ref doc for stack (3)

Browse Source 
Fix docs for stack-find, stack-show, stack-list APIs.
Major changes include:

- Revise stack query parameters to differentiate them from stack
  object body fields.
- Added 'resolve_outputs' to stack-find interface.
- Added response sample and documentation for stack-find API.
  We should faithfully document the 302 status code and body.
- Added missing parameter 'stacks' for stack-list call.
- Added missing 'X-Openstack-Request-Id' parameter in responses.

Change-Id: Ifc4937a254ff766ae83c80c009047d926eebf72f
This commit is contained in:
tengqm 2016-08-18 08:14:40 -04:00
parent d130a726cd
commit a2a028be90
6 changed files with 240 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -92,13 +92,6 @@ type_name:
type: string
# variables in query
action_3:
description: |
Filters the stack list by an action. Use this
filter multiple times to filter by multiple actions.
in: query
required: false
type: string
deployment_server_id_query:
description: |
The UUID of the target server.
@ -107,19 +100,13 @@ deployment_server_id_query:
type: string
global_tenant:
description: |
Set to ``true`` to include stacks from all
tenants in the stack list. Specify policy requirements in the
Orchestration ``policy.json`` file. Default is ``false``.
Set to ``true`` to include stacks from all tenants (projects) in the stack
list. Specify policy requirements in the Orchestration ``policy.json``
file.
in: query
required: false
default: false
type: boolean
id_4:
description: |
Filters the stack list by a stack ID. Use this
filter multiple times to filter by multiple IDs.
in: query
required: false
type: string
ignore_errors:
description: |
List of comma separated error codes to ignore.
@ -130,20 +117,18 @@ ignore_errors:
type: string
limit:
description: |
Requests a page size of items. Returns a number
of items up to a limit value. Use the ``limit`` parameter to make
an initial limited request and use the ID of the last-seen item
from the response as the ``marker`` parameter value in a
subsequent limited request.
Requests a page size of items. Returns a number of items up to a limit
value. Use the ``limit`` parameter to make an initial limited request and
use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
marker:
description: |
The ID of the last-seen item. Use the ``limit``
parameter to make an initial limited request and use the ID of the
last-seen item from the response as the ``marker`` parameter value
in a subsequent limited request.
The ID of the last-seen item. Use the ``limit`` parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
@ -155,13 +140,6 @@ name:
in: query
required: false
type: string
name_4:
description: |
Filters the stack list by a name. Use this filter
multiple times to filter by multiple names.
in: query
required: false
type: string
nested_depth:
description: |
Includes resources from nested stacks up to the
@ -171,30 +149,36 @@ nested_depth:
type: integer
not_tags:
description: |
Lists stacks that do not contain one or more
simple string tags. To specify multiple tags, separate the tags
with commas. For example, ``tag1,tag2``. The boolean AND
expression is used to combine multiple tags.
Lists stacks that do not contain one or more simple string tags. To
specify multiple tags, separate the tags with commas. For example,
``tag1,tag2``. The boolean AND expression is used to combine multiple tags.
in: query
required: false
type: string
not_tags_any:
description: |
Lists stacks that do not contain one or more
simple string tags. To specify multiple tags, separate the tags
with commas. For example, ``tag1,tag2``. The boolean OR expression
is used to combine multiple tags.
Lists stacks that do not contain one or more simple string tags. To specify
multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
The boolean OR expression is used to combine multiple tags.
in: query
required: false
type: string
owner_id:
owner_id_query:
description: |
Filters the stack list by an owner ID, which is
the ID of the parent stack of listed stack. Use this filter
multiple times to filter by multiple owner IDs.
Filters the stack list by an owner ID, which is the ID of the parent stack
of listed stack. Use this filter multiple times to filter by multiple
owner IDs.
in: query
required: false
type: string
resolve_outputs:
description: |
A boolean indicating whether the outputs section of a stack should be
resolved.
in: query
required: false
default: true
type: boolean
resource_action:
description: |
Stack resource action. Valid resource actions are ``ADOPT``, ``CHECK``,
@ -226,24 +210,22 @@ resource_type:
type: string
show_deleted:
description: |
Set to ``true`` to include deleted stacks in the
list. Default is ``false``, which excludes deleted stacks from the
list.
Set to ``true`` to include deleted stacks in the list.
in: query
required: false
default: false
type: boolean
show_nested:
description: |
Set to ``true`` to include nested stacks in the
list. Default is ``false``, which excludes nested stacks from the
list.
Set to ``true`` to include nested stacks in the list.
in: query
required: false
default: false
type: boolean
sort_dir:
description: |
The sort direction of the list. A valid value is
``asc`` (ascending) or ``desc`` (descending).
The sort direction of the list. A valid value is ``asc`` (ascending) or
``desc`` (descending).
in: query
required: false
type: string
@ -254,17 +236,52 @@ sort_keys:
in: query
required: false
type: string
sort_keys_1:
stack_action_query:
description: |
Sorts the stack list by ``stack_name``,
``stack_status``, ``creation_time``, or ``updated_time`` key.
Filters the stack list by an action. Use this filter multiple times to
filter by multiple actions.
in: query
required: false
type: string
status_5:
stack_id_query:
description: |
Filters the stack list by a status. Use this
filter multiple times to filter by multiple statuses.
Filters the stack list by a stack ID. Use this filter multiple times to
filter by multiple IDs.
in: query
required: false
type: string
stack_name_query:
description: |
Filters the stack list by a name. Use this filter multiple times to filter
by multiple names.
in: query
required: false
type: string
stack_sort_keys:
description: |
Sorts the stack list by ``stack_name``, ``stack_status``,
``creation_time``, or ``updated_time`` key.
in: query
required: false
type: string
stack_status_query:
description: |
Filters the stack list by a status. Use this filter multiple times to
filter by multiple statuses.
in: query
required: false
type: string
stack_tenant_query:
description: |
Filters the stack list by a tenant. Use this filter multiple times to
filter by multiple tenants.
in: query
required: false
type: string
stack_user_query:
description: |
Filters the stack list by a user name. Use this filter multiple times to
filter by multiple user names.
in: query
required: false
type: string
@ -278,35 +295,19 @@ support_status_1:
in: query
required: false
type: string
tags_1:
description: |
Lists stacks that contain one or more simple
string tags. To specify multiple tags, separate the tags with
commas. For example, ``tag1,tag2``. The boolean AND expression is
used to combine multiple tags.
in: query
required: false
type: string
tags_any:
description: |
Lists stacks that contain one or more simple
string tags. To specify multiple tags, separate the tags with
commas. For example, ``tag1,tag2``. The boolean OR expression is
used to combine multiple tags.
Lists stacks that contain one or more simple string tags. To specify
multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
The boolean OR expression is used to combine multiple tags.
in: query
required: false
type: string
tenant:
tags_query:
description: |
Filters the stack list by a tenant. Use this
filter multiple times to filter by multiple tenants.
in: query
required: false
type: string
username:
description: |
Filters the stack list by a user name. Use this
filter multiple times to filter by multiple user names.
Lists stacks that contain one or more simple string tags. To specify
multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
The boolean AND expression is used to combine multiple tags.
in: query
required: false
type: string
@ -320,11 +321,11 @@ version:
type: string
with_count:
description: |
Set to ``true`` to include a count key in the
response. The count key value is the number of stacks that match
the query criteria. Default is ``false``.
Set to ``true`` to include a count key in the response. The ``count`` key
value is the number of stacks that match the query criteria.
in: query
required: false
default: false
type: boolean
with_description:
description: |
@ -431,6 +432,12 @@ check:
in: body
required: true
type: string
code:
description: |
The response code to a resource find request. e.g. ``302 Found``.
in: body
required: True
type: string
config:
description: |
Configuration script or manifest that defines
@ -607,7 +614,7 @@ deployment_updated_time:
type: string
description:
description: |
The description of the resource.
The description of the stack resource.
in: body
required: true
type: string
@ -779,6 +786,12 @@ logical_resource_id:
in: body
required: true
type: string
message:
description: |
The message in the response to a resource find request.
in: body
required: true
type: string
name_1:
description: |
The name of the configuration to create.
@ -1095,6 +1108,13 @@ stack:
in: body
required: true
type: object
stack_disable_rollback:
description: |
Whether deletion of all stack resources when stack creation fails is
enabled.
in: body
required: true
type: boolean
stack_id:
description: |
The UUID of the stack.
@ -1121,7 +1141,7 @@ stack_outputs:
type: array
stack_owner:
description: |
The owner of the stack
The owner of the stack.
in: body
required: true
type: string
@ -1145,12 +1165,6 @@ stack_stack_user_project_id:
required: true
type: string
stack_status:
description: |
The status of the active stack.
in: body
required: true
type: string
stack_status_1:
description: |
The status of the stack.
in: body
@ -1181,6 +1195,12 @@ stack_user_project_id:
in: body
required: false
type: string
stacks:
description: |
A list of ``stack`` object.
in: body
required: true
type: array
status:
description: |
The status of the heat engine.
@ -1277,6 +1297,12 @@ timeout_mins:
in: body
required: false
type: integer
title:
description: |
The title of the response to a resource find request. e.g. ``Found``.
in: body
required: true
type: string
topic:
description: |
The topic of the heat engine.

28
api-ref/source/v1/samples/stack-find-response.json
View File

@ -1,27 +1,5 @@
{
"stack": {
"capabilities": [],
"creation_time": "2014-06-04T20:36:12Z",
"description": "sample stack",
"disable_rollback": true,
"id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"links": [
{
"href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"rel": "self"
}
],
"notification_topics": [],
"outputs": [],
"parameters": {
"OS::stack_id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"OS::stack_name": "simple_stack"
},
"stack_name": "simple_stack",
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"template_description": "sample stack",
"timeout_mins": null,
"updated_time": null
}
"code": "302 Found",
"message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd</a>;\nyou should be redirected automatically.\n\n",
"title": "Found"
}

11
api-ref/source/v1/samples/stack-show-response.json
View File

@ -2,6 +2,7 @@
"stack": {
"capabilities": [],
"creation_time": "2014-06-03T20:59:46Z",
"deletion_time": null,
"description": "sample stack",
"disable_rollback": true,
"id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
@ -18,15 +19,15 @@
"OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"OS::stack_name": "simple_stack"
},
"parent": null,
"stack_name": "simple_stack",
"stack_owner": "simple_username",
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"template_description": "sample stack",
"stack_user_project_id": "65728b74-cfe7-4f17-9c15-11d4f686e591",
"timeout_mins": "",
"updated_time": "",
"parent": "",
"tags": ""
"tags": null,
"template_description": "sample stack",
"timeout_mins": null,
"updated_time": null
}
}

10
api-ref/source/v1/samples/stacks-list-response.json
View File

@ -2,6 +2,7 @@
"stacks": [
{
"creation_time": "2014-06-03T20:59:46Z",
"deletion_time": null,
"description": "sample stack",
"id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"links": [
@ -10,15 +11,14 @@
"rel": "self"
}
],
"parent": null,
"stack_name": "simple_stack",
"stack_owner": null,
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"updated_time": "",
"tags": null,
"parent": null,
"stack_owner": null,
"stack_user_project_id": "71510cbd459a49ac989ca1055de7038b",
"deletion_time": null
"tags": null,
"updated_time": null
}
]
}

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

@ -131,7 +131,7 @@ Response Parameters
- stack_user_project_id: stack_stack_user_project_id
- tags: stack_tags
- template_description: template_description
- timeout_mins: timeout_mins
- timeout_mins: stack_timeout_mins
- updated_time: updated_time
Response Example
@ -148,8 +148,18 @@ List stacks
Lists active stacks.
Normal response codes: 200
Error response codes:500,401,400,
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 500
Request Parameters
------------------
@ -157,23 +167,23 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- id: id
- status: status
- name: name
- action: action
- tenant: tenant
- username: username
- owner_id: owner_id
- id: stack_id_query
- status: stack_status_query
- name: stack_name_query
- action: stack_action_query
- tenant: stack_tenant_query
- username: stack_user_query
- owner_id: owner_id_query
- limit: limit
- marker: marker
- sort_keys: stack_sort_keys
- sort_dir: sort_dir
- show_deleted: show_deleted
- show_nested: show_nested
- sort_keys: sort_keys
- tags: tags
- tags: tags_query
- tags_any: tags_any
- not_tags: not_tags
- not_tags_any: not_tags_any
- sort_dir: sort_dir
- global_tenant: global_tenant
- with_count: with_count
@ -182,19 +192,20 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- stacks: stacks
- creation_time: creation_time
- deletion_time: deletion_time
- description: description
- links: links
- stack_status_reason: stack_status_reason
- stack_name: stack_name
- tags: tags
- creation_time: creation_time
- updated_time: updated_time
- deletion_time: deleted_at
- stack_status: stack_status
- stack_owner: owner_id
- stack_user_project_id: stack_user_project_id
- parent: parent
- id: id
- stack_name: stack_name
- stack_owner: stack_owner
- stack_status: stack_status
- stack_status_reason: stack_status_reason
- tags: stack_tags
- updated_time: updated_time
- stack_user_project_id: stack_stack_user_project_id
Response Example
----------------
@ -210,23 +221,52 @@ Find stack
Finds the canonical URL for a stack.
Also works with verbs other than GET , so that you can perform PUT
and DELETE operations on a current stack. Set your client to follow
redirects. When redirecting, the request method should not change
as defined in RFC2626. However, in many clients the default
behavior is to change the method to GET when you receive a ``302``
response code because this behavior is ubiquitous in web browsers.
Also works with verbs other than GET, so that you can perform PUT and DELETE
operations on a current stack. Set your client to follow redirects. When
redirecting, the request method should not change as defined in RFC2626.
However, in many clients the default behavior is to change the method to GET
when you receive a ``302`` response code because this behavior is ubiquitous
in web browsers.
Error response codes:302,404,500,401,400,
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 302
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_name: stack_name_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
- X-Openstack-Request-Id: request_id
- code: code
- message: message
- title: title
Response Example
----------------
.. literalinclude:: samples/stack-find-response.json
:language: javascript
Show stack details
==================
@ -235,8 +275,19 @@ Show stack details
Shows details for a stack.
Normal response codes: 200
Error response codes:404,500,401,400,
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
@ -246,31 +297,35 @@ Request Parameters
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- resolve_outputs: resolve_outputs
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- parent: parent
- updated_time: updated_time
- description: description
- links: links
- stack_status_reason: stack_status_reason
- stack_name: stack_name
- outputs: outputs
- tags: tags
- creation_time: creation_time
- X-Openstack-Request-Id: request_id
- stack: stack
- capabilities: capabilities
- creation_time: creation_time
- deletion_time: deletion_time
- description: description
- disable_rollback: stack_disable_rollback
- id: stack_id
- links: links
- notification_topics: notification_topics
- timeout_mins: timeout_mins
- outputs: stack_outputs
- parameters: stack_parameters
- parent: parent
- stack_name: stack_name
- stack_owner: stack_owner
- stack_status: stack_status
- stack: stack
- parameters: parameters
- id: id
- stack_user_project_id: stack_user_project_id
- stack_status_reason: stack_status_reason
- stack_user_project_id: stack_stack_user_project_id
- tags: stack_tags
- template_description: template_description
- timeout_mins: stack_timeout_mins
- updated_time: updated_time
Response Example
----------------

5
api-ref/source/v1/status.yaml
View File

@ -19,6 +19,11 @@
default: |
There are multiple choices for resources. The request has to be more
specific to successfully retrieve one of these resources.
302:
default: |
The response is about a redirection hint. The header of the response
usually contains a 'location' value where requesters can check to track
the real location of the resource.
#################
# Error Codes #