api-ref doc for stack (3)

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

api-ref/source/v1/parameters.yaml

@@ -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
+    Set to ``true`` to include stacks from all tenants (projects) in the stack
-    tenants in the stack list. Specify policy requirements in the
+    list. Specify policy requirements in the Orchestration ``policy.json``
-    Orchestration ``policy.json`` file. Default is ``false``.
+    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
+    Requests a page size of items. Returns a number of items up to a limit
-    of items up to a limit value. Use the ``limit`` parameter to make
+    value. Use the ``limit`` parameter to make an initial limited request and
-    an initial limited request and use the ID of the last-seen item
+    use the ID of the last-seen item from the response as the ``marker``
-    from the response as the ``marker`` parameter value in a
+    parameter value in a subsequent limited request.
-    subsequent limited request.
   in: query
   required: false
   type: integer
 marker:
   description: |
-    The ID of the last-seen item. Use the ``limit``
+    The ID of the last-seen item. Use the ``limit`` parameter to make an
-    parameter to make an initial limited request and use the ID of the
+    initial limited request and use the ID of the last-seen item from the
-    last-seen item from the response as the ``marker`` parameter value
+    response as the ``marker`` parameter value in a subsequent limited request.
-    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
+    Lists stacks that do not contain one or more simple string tags. To
-    simple string tags. To specify multiple tags, separate the tags
+    specify multiple tags, separate the tags with commas. For example,
-    with commas. For example, ``tag1,tag2``. The boolean AND
+    ``tag1,tag2``. The boolean AND expression is used to combine multiple tags.
-    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
+    Lists stacks that do not contain one or more simple string tags. To specify
-    simple string tags. To specify multiple tags, separate the tags
+    multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
-    with commas. For example, ``tag1,tag2``. The boolean OR expression
+    The boolean OR expression is used to combine multiple tags.
-    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
+    Filters the stack list by an owner ID, which is the ID of the parent stack
-    the ID of the parent stack of listed stack. Use this filter
+    of listed stack. Use this filter multiple times to filter by multiple
-    multiple times to filter by multiple owner IDs.
+    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
+    Set to ``true`` to include deleted stacks in the list.
-    list. Default is ``false``, which excludes deleted stacks from the
-    list.
   in: query
   required: false
+  default: false
   type: boolean
 show_nested:
   description: |
-    Set to ``true`` to include nested stacks in the
+    Set to ``true`` to include nested stacks in the list.
-    list. Default is ``false``, which excludes nested stacks from the
-    list.
   in: query
   required: false
+  default: false
   type: boolean
 sort_dir:
   description: |
-    The sort direction of the list. A valid value is
+    The sort direction of the list. A valid value is ``asc`` (ascending) or
-    ``asc`` (ascending) or ``desc`` (descending).
+    ``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``,
+    Filters the stack list by an action. Use this filter multiple times to
-    ``stack_status``, ``creation_time``, or ``updated_time`` key.
+    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
+    Filters the stack list by a stack ID. Use this filter multiple times to
-    filter multiple times to filter by multiple statuses.
+    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
+    Lists stacks that contain one or more simple string tags. To specify
-    string tags. To specify multiple tags, separate the tags with
+    multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
-    commas. For example, ``tag1,tag2``. The boolean OR expression is
+    The boolean OR expression is used to combine multiple tags.
-    used to combine multiple tags.
   in: query
   required: false
   type: string
-tenant:
+tags_query:
   description: |
-    Filters the stack list by a tenant. Use this
+    Lists stacks that contain one or more simple string tags. To specify
-    filter multiple times to filter by multiple tenants.
+    multiple tags, separate the tags with commas. For example, ``tag1,tag2``.
-  in: query
+    The boolean AND expression is used to combine multiple tags.
-  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.
   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
+    Set to ``true`` to include a count key in the response. The ``count`` key
-    response. The count key value is the number of stacks that match
+    value is the number of stacks that match the query criteria.
-    the query criteria. Default is ``false``.
   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.

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

@@ -1,27 +1,5 @@
 {
-    "stack": {
+    "code": "302 Found",
-        "capabilities": [],
+    "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",
-        "creation_time": "2014-06-04T20:36:12Z",
+    "title": "Found"
-        "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
-    }
 }

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

@@ -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": "",
+        "tags": null,
-        "updated_time": "",
+        "template_description": "sample stack",
-        "parent": "",
+        "timeout_mins": null,
-        "tags": ""
+        "updated_time": null
     }
 }

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

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

api-ref/source/v1/stacks.inc

@@ -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
+Response Codes
-Error response codes:500,401,400,
+--------------
+
+.. 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
+   - id: stack_id_query
-   - status: status
+   - status: stack_status_query
-   - name: name
+   - name: stack_name_query
-   - action: action
+   - action: stack_action_query
-   - tenant: tenant
+   - tenant: stack_tenant_query
-   - username: username
+   - username: stack_user_query
-   - owner_id: owner_id
+   - 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_query
-   - tags: tags
    - 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
+Also works with verbs other than GET, so that you can perform PUT and DELETE
-and DELETE operations on a current stack. Set your client to follow
+operations on a current stack. Set your client to follow redirects. When
-redirects. When redirecting, the request method should not change
+redirecting, the request method should not change as defined in RFC2626.
-as defined in RFC2626. However, in many clients the default
+However, in many clients the default behavior is to change the method to GET
-behavior is to change the method to GET when you receive a ``302``
+when you receive a ``302`` response code because this behavior is ubiquitous
-response code because this behavior is ubiquitous in web browsers.
+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
+Response Codes
-Error response codes:404,500,401,400,
+--------------
+
+.. 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
+   - X-Openstack-Request-Id: request_id
-   - updated_time: updated_time
+   - stack: stack
-   - description: description
-   - links: links
-   - stack_status_reason: stack_status_reason
-   - stack_name: stack_name
-   - outputs: outputs
-   - tags: tags
-   - creation_time: creation_time
    - 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
+   - stack_status_reason: stack_status_reason
-   - parameters: parameters
+   - stack_user_project_id: stack_stack_user_project_id
-   - id: id
+   - tags: stack_tags
-   - stack_user_project_id: stack_user_project_id
    - template_description: template_description
+   - timeout_mins: stack_timeout_mins
+   - updated_time: updated_time
 
 Response Example
 ----------------

api-ref/source/v1/status.yaml

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