api-ref - stack resources

This patch fixes the problems found in the api-ref doc for stack
resources. More specifically, changes include:
- Add 'physical_resource_id' as a query parameter;
- Add 'resource_id' as a query parameter;
- Add 'with_attr' parameter when showing resource;
- Add API doc for resource-mark-unhealthy;
- Add response parameters for resource-show-metadata API;
- Add missing fields such 'links', openstack-request-id in some responses.
- Add a special description for the 400 status code of resource-signal.

Change-Id: I6e6889e79f25431278e82b2c499267d8853470d1

api-ref/source/v1/index.rst

@@ -24,7 +24,7 @@ Orchestration Service API v1
 .. include:: general-info.inc
 .. include:: versions.inc
 .. include:: stacks.inc
-.. include:: stack-resources.inc
+.. include:: resources.inc
 .. include:: stack-outputs.inc
 .. include:: stack-snapshots.inc
 .. include:: stack-actions.inc

api-ref/source/v1/parameters.yaml

@@ -141,10 +141,11 @@ marker:
   type: string
 nested_depth:
   description: |
-    Includes resources from nested stacks up to the
+    Includes resources from nested stacks up to the ``nested_depth`` levels
-    ``nested_depth`` levels of recursion.
+    of recursion.
   in: query
   required: false
+  default: 0
   type: integer
 not_tags:
   description: |
@@ -170,6 +171,14 @@ owner_id_query:
   in: query
   required: false
   type: string
+physical_resource_id_query:
+  description: |
+    Filters the resource list by the ID of physical resource represented by
+    a stack resource. Use this filter multiple times to filter by multiple
+    physical resource IDs.
+  in: query
+  required: false
+  type: string
 resolve_outputs:
   description: |
     A boolean indicating whether the outputs section of a stack should be
@@ -178,7 +187,7 @@ resolve_outputs:
   required: false
   default: true
   type: boolean
-resource_action:
+resource_action_query:
   description: |
     Stack resource action. Valid resource actions are ``ADOPT``, ``CHECK``,
     ``CREATE``, ``DELETE``, ``INIT``, ``RESTORE``, ``RESUME``,
@@ -186,6 +195,13 @@ resource_action:
   in: query
   required: false
   type: string
+resource_id_query:
+  description: |
+    Filters the resource list by the logical ID of stack resources. Use this
+    filter multiple times to filter by multiple resource IDs.
+  in: query
+  required: false
+  type: string
 resource_name_query:
   description: |
     Filters the result list by a resource name. You can use this filter
@@ -193,17 +209,20 @@ resource_name_query:
   in: query
   required: false
   type: string
-resource_status:
+resource_status_query:
   description: |
     Stack resource status. Valid resource statuses are ``COMPLETE``,
-    ``FAILED`` and ``IN_PROGRESS``.
+    ``FAILED`` and ``IN_PROGRESS``. This can be specified more than once to
+    filter the results by multiple resource statuses.
   in: query
   required: false
   type: string
 resource_type_query:
   description: |
     Stack resource type. Valid resource types include ``OS::Cinder::Volume``,
-    ``OS::Nova::Server``, ``OS::Neutron::Port`` and so on.
+    ``OS::Nova::Server``, ``OS::Neutron::Port`` and so on. This parameter
+    can be specified more than once to filter results by multiple resource
+    types.
   in: query
   required: false
   type: string
@@ -330,6 +349,13 @@ type_version_query:
   in: query
   required: false
   type: string
+with_attr:
+  description: |
+    Includes detailed resource information for the resource.
+  in: query
+  required: false
+  default: false
+  type: boolean
 with_count:
   description: |
     Set to ``true`` to include a count key in the response. The ``count`` key
@@ -347,10 +373,11 @@ with_description:
   type: boolean
 with_detail:
   description: |
-    Enables detailed resource information for each
+    Enables detailed resource information for each resource in list of
-    resource in list of resources.
+    resources.
   in: query
   required: false
+  default: false
   type: boolean
 
 # variables in body
@@ -773,12 +800,25 @@ logical_resource_id:
   in: body
   required: true
   type: string
+mark_unhealthy:
+  description: |
+    A boolean indicating whether the target resource should be marked as
+    unhealthy.
+  in: body
+  required: true
+  type: boolean
 message:
   description: |
     The message in the response to a resource find request.
   in: body
   required: true
   type: string
+metadata:
+  description: |
+    The metadata of a resource.
+  in: body
+  required: true
+  type: object
 name_1:
   description: |
     The name of the configuration to create.
@@ -1012,15 +1052,13 @@ required:
   type: boolean
 required_by:
   description: |
-    The list of resources that require this stack
+    The list of resources that require this stack resource.
-    resource.
   in: body
   required: true
   type: array
 resource:
   description: |
-    Key and value pairs that contain stack resource
+    Key and value pairs that contain stack resource properties.
-    properties.
   in: body
   required: true
   type: object
@@ -1031,13 +1069,22 @@ resource_changes:
   in: body
   required: true
   type: object
+resource_links:
+  description: |
+    A list of URLs for the resource. Each URL is a JSON object with an ``href``
+    key indicating the URL and a ``rel`` key indicating its relationship to
+    the resource in question. There may be multiple links returned. The
+    ``self`` relationship identifies the URL of the resource itself.
+  in: body
+  required: true
+  type: array
 resource_name:
   description: |
     The name of the resource.
   in: body
   required: true
   type: string
-resource_status_1:
+resource_status:
   description: |
     The status of the resource.
   in: body
@@ -1074,6 +1121,13 @@ resource_types_simple:
   in: body
   required: true
   type: array
+resource_upudate_status_reason:
+  description: |
+    The reason for the current stack resource state.
+  in: body
+  required: false
+  default: ''
+  type: string
 resources:
   description: |
     A map of resource names and their properties.
@@ -1098,6 +1152,12 @@ resources_abandon:
   in: body
   required: true
   type: object
+resources_list:
+  description: |
+    A list of resource objects.
+  in: body
+  required: true
+  type: array
 resume:
   description: |
     Specify the ``resume`` action in the request

api-ref/source/v1/resources.inc

@@ -8,7 +8,7 @@ Stack resources
 Find stack resources
 ====================
 
-.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/resources
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_identity}/resources
 
 Finds the canonical URL for a resource list of a stack.
 
@@ -19,7 +19,17 @@ the resource list for deleted stacks, use the following endpoint:
 
    /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
 
-Error response codes:302,
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 302
+
+.. rest_status_code:: success status.yaml
+
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -27,7 +37,21 @@ Request Parameters
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
-   - stack_name: stack_name_url
+   - stack_identity: stack_identity
+
+Response Parameter
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - location: location
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-find-response.json
+   :language: javascript
 
 
 List stack resources
@@ -39,8 +63,18 @@ Lists resources in a stack based on filtering parameters like resource
 name, status, type, action, id and physical_resource_id. These parameters could
 be used multiple times.
 
-Normal response codes: 200
+Response Codes
-Error response codes:404,401,400,
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: success status.yaml
+
+   - 400
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -50,31 +84,32 @@ Request Parameters
    - tenant_id: tenant_id
    - stack_name: stack_name_url
    - stack_id: stack_id_url
+   - type: resource_type_query
+   - status: resource_status_query
+   - name: resource_name_query
+   - action: resource_action_query
+   - id: resource_id_query
+   - physical_resource_id: physical_resource_id_query
    - nested_depth: nested_depth
    - with_detail: with_detail
-   - name: resource_name_query
-   - status: resource_status
-   - type: resource_type_query
-   - action: resource_action
-   - id: logical_resource_id
-   - physical_resource_id: physical_resource_id
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - resource_name: resource_name
+   - X-Openstack-Request-Id: request_id
-   - description: description
+   - resources: resources_list
-   - logical_resource_id: logical_resource_id
    - creation_time: creation_time
-   - resource_status: resource_status
+   - links: links
-   - updated_time: updated_time
+   - logical_resource_id: logical_resource_id
-   - required_by: required_by
-   - resources: resources
-   - resource_status_reason: resource_status_reason
    - physical_resource_id: physical_resource_id
+   - required_by: required_by
+   - resource_name: resource_name
+   - resource_status: resource_status
+   - resource_status_reason: resource_status_reason
    - resource_type: resource_type
+   - updated_time: updated_time
 
 Response Example
 ----------------
@@ -83,34 +118,6 @@ Response Example
    :language: javascript
 
 
-Show resource metadata
-======================
-
-.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata
-
-Shows metadata for a resource.
-
-
-Normal response codes: 200
-Error response codes:
-
-Request Parameters
-------------------
-
-.. rest_parameters:: parameters.yaml
-
-   - tenant_id: tenant_id
-   - stack_name: stack_name_url
-   - stack_id: stack_id_url
-   - resource_name: resource_name_url
-
-Response Example
-----------------
-
-.. literalinclude:: samples/resource-metadata-response.json
-   :language: javascript
-
-
 Show resource data
 ==================
 
@@ -118,9 +125,76 @@ Show resource data
 
 Shows data for a resource.
 
+Response Codes
+--------------
 
-Normal response codes: 200
+.. rest_status_code:: success status.yaml
-Error response codes:404,401,400,
+
+   - 200
+
+.. rest_status_code:: success status.yaml
+
+   - 400
+   - 401
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url
+   - resource_name: resource_name_url
+   - with_attr: with_attr
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - resource: resource
+   - attributes: attributes
+   - creation_time: creation_time
+   - description: description
+   - links: resource_links
+   - logical_resource_id: logical_resource_id
+   - physical_resource_id: physical_resource_id
+   - required_by: required_by
+   - resource_name: resource_name
+   - resource_status: resource_status
+   - resource_status_reason: resource_status_reason
+   - resource_type: resource_type
+   - updated_time: updated_time
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-show-response.json
+   :language: javascript
+
+
+Show resource metadata
+======================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata
+
+Shows metadata for a resource.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: success status.yaml
+
+   - 400
+   - 401
+   - 404
 
 Request Parameters
 ------------------
@@ -137,22 +211,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - resource_name: resource_name
+   - X-Openstack-Request-Id: request_id
-   - resource: resource
+   - metadata: metadata
-   - description: description
-   - logical_resource_id: logical_resource_id
-   - creation_time: creation_time
-   - resource_status: resource_status
-   - updated_time: updated_time
-   - required_by: required_by
-   - resource_status_reason: resource_status_reason
-   - physical_resource_id: physical_resource_id
-   - resource_type: resource_type
 
 Response Example
 ----------------
 
-.. literalinclude:: samples/resource-show-response.json
+.. literalinclude:: samples/resource-metadata-response.json
    :language: javascript
 
 
@@ -163,19 +228,25 @@ Send a signal to a resource
 
 Sends a signal to a resource.
 
-The contents of the request body depends on the resource to which
+Response Codes
-you send a signal.
+--------------
 
-Some resources cannot receive signals. If you send them a signal,
+.. rest_status_code:: success status.yaml
-they return a 400 error code.
 
+   - 200
 
-Normal response codes: 200
+.. rest_status_code:: success status.yaml
-Error response codes:
+
+   - 400: resource_signal
+   - 401
+   - 404
 
 Request Parameters
 ------------------
 
+The contents of the request body depends on the resource to which you send a
+signal.
+
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
@@ -187,3 +258,41 @@ Response Example
 ----------------
 
 This operation does not return a response body.
+
+
+Mark a resource unhealthy
+===========================
+
+.. rest_method::  PATCH /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}
+
+Mark the specified resource in the stack as unhealthy.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: success status.yaml
+
+   - 400
+   - 401
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url
+   - resource_name: resource_name_url
+   - mark_unhealthy: mark_unhealthy
+   - resource_status_reason: resource_update_status_reason
+
+Response Example
+----------------
+
+This operation does not return a response body.

api-ref/source/v1/stack-events.inc

@@ -25,8 +25,8 @@ Request
    - tenant_id: tenant_id
    - stack_id: stack_id_url
    - stack_name: stack_name_url
-   - resource_action: resource_action
+   - resource_action: resource_action_query
-   - resource_status: resource_status
+   - resource_status: resource_status_query
    - resource_name: resource_name_query
    - resource_type: resource_type_query
    - limit: limit
@@ -111,8 +111,8 @@ Request
    - stack_id: stack_id_url
    - stack_name: stack_name_url
    - resource_name: resource_name_url
-   - resource_action: resource_action
+   - resource_action: resource_action_query
-   - resource_status: resource_status
+   - resource_status: resource_status_query
    - resource_type: resource_type_query
    - limit: limit
    - marker: marker

api-ref/source/v1/status.yaml

@@ -32,6 +32,8 @@
 400:
   default: |
     Some content in the request was invalid.
+  resource_signal: |
+    The target resource doesn't support receiving a signal.
 401:
   default: |
     User must authenticate before making a request.