openstack/heat
Code Issues Proposed changes

api-ref - stack resources

Browse Source 
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
This commit is contained in:
tengqm 2016-08-20 03:57:50 -04:00 committed by Qiming Teng
parent 14a7304a62
commit 81d92bebb3
5 changed files with 256 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api-ref/source/v1/index.rst
View File

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

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

@ -141,10 +141,11 @@ marker:
type: string
nested_depth:
description: |
Includes resources from nested stacks up to the
``nested_depth`` levels of recursion.
Includes resources from nested stacks up to the ``nested_depth`` levels
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
resource in list of resources.
Enables detailed resource information for each resource in list of
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
resource.
The list of resources that require this stack resource.
in: body
required: true
type: array
resource:
description: |
Key and value pairs that contain stack resource
properties.
Key and value pairs that contain stack resource 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

243
api-ref/source/v1/stack-resources.inc → api-ref/source/v1/resources.inc
View File

@ -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
Error response codes:404,401,400,
Response Codes
--------------
.. 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
- description: description
- logical_resource_id: logical_resource_id
- X-Openstack-Request-Id: request_id
- resources: resources_list
- creation_time: creation_time
- resource_status: resource_status
- updated_time: updated_time
- required_by: required_by
- resources: resources
- resource_status_reason: resource_status_reason
- links: 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
----------------
@ -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
Error response codes:404,401,400,
.. 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
- 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
- resource: resource
- 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
- X-Openstack-Request-Id: request_id
- metadata: metadata
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
you send a signal.
Response Codes
--------------
Some resources cannot receive signals. If you send them a signal,
they return a 400 error code.
.. rest_status_code:: success status.yaml
- 200
Normal response codes: 200
Error response codes:
.. rest_status_code:: success status.yaml
- 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.

8
api-ref/source/v1/stack-events.inc
View File

@ -25,8 +25,8 @@ Request
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_action: resource_action
- resource_status: resource_status
- resource_action: resource_action_query
- 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_status: resource_status
- resource_action: resource_action_query
- resource_status: resource_status_query
- resource_type: resource_type_query
- limit: limit
- marker: marker

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

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