api-ref doc for stack (2)

This patch continues the fix to the api-ref doc for stack resource. To
ensure upcoming patches are not messing up the parameter defintions,
this patch is cleansing up the parameters that appear both in URLs and
request/response bodies: 'stack_id', 'stack_name', 'resource_name',
'event_id', 'snapshot_id', etc. These parameters sometimes are playing
different roles although the name is the same.
Other fixes included in this patch:

- added back the stack-outputs and stack-snapshots into index
- split resource-types out of stack-templates and add reference to it
  into index (git misunderstood this as a renaming, :))

Change-Id: I2b486a9b85d23d3225a5701c2265ecea2f4712f7
This commit is contained in:
tengqm 2016-08-18 05:58:24 -04:00
parent fa39e4b1fd
commit d130a726cd
9 changed files with 411 additions and 518 deletions

View File

@ -23,6 +23,7 @@ Orchestration Service API v1
.. include:: build-info.inc
.. include:: general-info.inc
.. include:: heat-versions.inc
.. include:: resource-types.inc
.. include:: service-status.inc
.. include:: software-config.inc
.. include:: stack-actions.inc
@ -30,3 +31,5 @@ Orchestration Service API v1
.. include:: stack-resources.inc
.. include:: stack-templates.inc
.. include:: stacks.inc
.. include:: stack-outputs.inc
.. include:: stack-snapshots.inc

View File

@ -34,7 +34,7 @@ deployment_server_id_url:
in: path
required: true
type: string
event_id:
event_id_url:
description: |
The UUID of the event that is related to the
resource in the stack.
@ -47,13 +47,13 @@ output_key_1:
in: path
required: false
type: string
resource_name:
resource_name_url:
description: |
The name of a resource in the stack.
in: path
required: false
type: string
snapshot_id:
snapshot_id_url:
description: |
The UUID of the snapshot.
in: path
@ -203,11 +203,10 @@ resource_action:
in: query
required: false
type: string
resource_name_2:
resource_name_query:
description: |
Filters the event list by a resource name. You
can use this filter multiple times to filter by multiple resource
names.
Filters the result list by a resource name. You can use this filter
multiple times to filter by multiple resource names.
in: query
required: false
type: string
@ -990,7 +989,7 @@ resource_description:
in: body
required: false
type: string
resource_name_1:
resource_name:
description: |
The name of the resource.
in: body
@ -1265,6 +1264,13 @@ template_url:
in: body
required: false
type: string
template_versions:
description: |
A list of template version object each describes the type name and version
information for a template version.
in: body
required: true
type: array
timeout_mins:
description: |
The timeout for stack creation in minutes.

View File

@ -0,0 +1,142 @@
.. -*- rst -*-
==============
Resource Types
==============
List resource types
===================
.. rest_method:: GET /v1/{tenant_id}/resource_types
Lists all supported template resource types.
Normal response codes: 200
Error response codes:401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- name: name
- version: version
- support_status: support_status
- with_description: with_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- template_versions: template_versions
- type: type
- version: version
- description: resource_description
Response Example
----------------
.. literalinclude:: samples/resource-types-list-response.json
:language: javascript
Show resource type template
===========================
.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name}/template
Shows the template representation for a resource type.
The returned template contains a single resource type. Each
resource property is mapped to a template parameter and each
resource attribute is mapped to a template output.
You can use these templates as a starting place for creating
customized, template-based resources or as examples of using the
particular resource in another template.
Use the ``template_type`` query parameter to specify the resource
template type. Default type is ``cfn``. The ``hot`` template type
is supported. For example:
::
/v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn
Normal response codes: 200
Error response codes:404,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Outputs: Outputs
- HeatTemplateFormatVersion: HeatTemplateFormatVersion
- Resources: Resources
- Parameters: Parameters
Response Example
----------------
.. literalinclude:: samples/resource-type-template-response.json
:language: javascript
Show resource type schema
=========================
.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name}
Shows the interface schema for a resource type.
A schema describes the properties that can be set on the resource,
their types, constraints, descriptions, and default values.
Additionally, the response shows the resource attributes and their
descriptions.
Normal response codes: 200
Error response codes:401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
- with_description: with_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: description
- required: required
- update_allowed: update_allowed
- support_status: support_status
- attributes: attributes
- type: type
- properties: properties
- description: resource_description
- resource_type: resource_type
Response Example
----------------
.. literalinclude:: samples/resource-schema-response.json
:language: javascript

View File

@ -7,7 +7,6 @@ Stack actions
Performs non-lifecycle operations on the stack. Specify the action
in the request body.
Suspend stack
=============
@ -15,20 +14,18 @@ Suspend stack
Suspends a stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- suspend: suspend
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- suspend: suspend
Request Example
---------------
@ -36,17 +33,12 @@ Request Example
.. literalinclude:: samples/stack-action-suspend-request.json
:language: javascript
Response Example
----------------
This operation does not return a response body.
Resume stack
============
@ -54,20 +46,18 @@ Resume stack
Resumes a suspended stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- resume: resume
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resume: resume
Request Example
---------------
@ -75,18 +65,12 @@ Request Example
.. literalinclude:: samples/stack-action-resume-request.json
:language: javascript
Response Example
----------------
This operation does not return a response body.
Cancel stack update
===================
@ -94,20 +78,18 @@ Cancel stack update
Cancels a currently running update of a stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- cancel_update: cancel_update
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- cancel_update: cancel_update
Request Example
---------------
@ -115,17 +97,12 @@ Request Example
.. literalinclude:: samples/stack-action-cancel-update-request.json
:language: javascript
Response Example
----------------
This operation does not return a response body.
Check stack resources
=====================
@ -133,20 +110,18 @@ Check stack resources
Checks whether the resources are in expected states for a stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- check: check
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- check: check
Request Example
---------------
@ -154,14 +129,7 @@ Request Example
.. literalinclude:: samples/stack-action-check-request.json
:language: javascript
Response Example
----------------
This operation does not return a response body.

View File

@ -5,6 +5,60 @@ Stack events
============
List stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events
Lists events for a stack based on filtering parameters like resource
name, status, type, action. These parameters could be used multiple times.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_action: resource_action
- resource_status: resource_status
- resource_name: resource_name_query
- resource_type: resource_type
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
- nested_depth: nested_depth
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript
Find stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/events
Finds the canonical URL for the event list of a stack.
Error response codes:302,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
Show event details
@ -24,14 +78,11 @@ Request
.. rest_parameters:: parameters.yaml
- resource_name: resource_name
- stack_name: stack_name
- tenant_id: tenant_id
- event_id: event_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_name: resource_name_url
- event_id: event_id_url
Response Example
----------------
@ -40,78 +91,6 @@ Response Example
:language: javascript
Find stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/events
Finds the canonical URL for the event list of a stack.
Error response codes:302,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
List stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events
Lists events for a stack based on filtering parameters like resource
name, status, type, action. These parameters could be used multiple times.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- resource_action: resource_action
- resource_status: resource_status
- resource_name: resource_name
- resource_type: resource_type
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
- nested_depth: nested_depth
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript
List resource events
====================
@ -123,16 +102,15 @@ Lists events for a stack resource.
Normal response codes: 200
Error response codes:404,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- resource_name: resource_name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_name: resource_name_url
- resource_action: resource_action
- resource_status: resource_status
- resource_type: resource_type
@ -141,17 +119,8 @@ Request
- sort_keys: sort_keys
- sort_dir: sort_dir
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript

View File

@ -4,6 +4,85 @@
Stack resources
===============
Find stack resources
====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/resources
Finds the canonical URL for a resource list of a stack.
The canonical URL is returned for only non-deleted stacks. To fetch
the resource list for deleted stacks, use the following endpoint:
::
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
Error response codes:302,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
List stack resources
====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
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,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- nested_depth: nested_depth
- with_detail: with_detail
- name: resource_name_query
- status: resource_status
- type: resource_type
- 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
- creation_time: creation_time
- resource_status: resource_status
- updated_time: updated_time
- required_by: required_by
- resources: resources
- resource_status_reason: resource_status_reason
- physical_resource_id: physical_resource_id
- resource_type: resource_type
Response Example
----------------
.. literalinclude:: samples/resources-list-response.json
:language: javascript
Show resource metadata
======================
@ -20,10 +99,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- resource_name: resource_name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_name: resource_name_url
Response Example
----------------
@ -48,10 +127,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- resource_name: resource_name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_name: resource_name_url
Response Parameters
-------------------
@ -77,84 +156,6 @@ Response Example
:language: javascript
List resources
==============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
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,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- nested_depth: nested_depth
- with_detail: with_detail
- name: resource_name
- status: resource_status
- type: resource_type
- 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
- creation_time: creation_time
- resource_status: resource_status
- updated_time: updated_time
- required_by: required_by
- resources: resources
- resource_status_reason: resource_status_reason
- physical_resource_id: physical_resource_id
- resource_type: resource_type
Response Example
----------------
.. literalinclude:: samples/resources-list-response.json
:language: javascript
Find stack resources
====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/resources
Finds the canonical URL for a resource list of a stack.
The canonical URL is returned for only non-deleted stacks. To fetch
the resource list for deleted stacks, use the following endpoint:
::
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
Error response codes:302,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
Send a signal to a resource
===========================
@ -177,10 +178,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- resource_name: resource_name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_name: resource_name_url
Response Example
----------------

View File

@ -4,8 +4,8 @@
Stack Snapshots
===============
Snapshot stack
==============
Snapshot a stack
================
.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
@ -19,10 +19,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- name: name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- name: name
Request Example
---------------
@ -65,10 +65,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- snapshot_id: snapshot_id_url
Response Parameters
-------------------
@ -107,9 +107,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
@ -145,10 +145,10 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- snapshot_id: snapshot_id_url
Restore snapshot
================
@ -167,7 +167,7 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- snapshot_id: snapshot_id_url

View File

@ -4,6 +4,30 @@
Templates
=========
List template versions
======================
.. rest_method:: GET /v1/{tenant_id}/template_versions
Lists all available template versions.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: samples/template-versions-response.json
:language: javascript
List template functions
=======================
@ -24,7 +48,6 @@ Request
- tenant_id: tenant_id
- template_version: template_version
Response Example
----------------
@ -32,90 +55,6 @@ Response Example
:language: javascript
List resource types
===================
.. rest_method:: GET /v1/{tenant_id}/resource_types
Lists all supported template resource types.
Normal response codes: 200
Error response codes:401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- name: name
- version: version
- support_status: support_status
- with_description: with_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- template_versions: template_versions
- type: type
- version: version
- description: resource_description
Response Example
----------------
.. literalinclude:: samples/resource-types-list-response.json
:language: javascript
List template versions
======================
.. rest_method:: GET /v1/{tenant_id}/template_versions
Lists all available template versions.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: samples/template-versions-response.json
:language: javascript
Validate template
=================
@ -123,11 +62,9 @@ Validate template
Validates a template.
Normal response codes: 200
Error response codes:
Request
-------
@ -145,8 +82,6 @@ Request Example
.. literalinclude:: samples/template-validate-request.json
:language: javascript
Response Parameters
-------------------
@ -156,177 +91,8 @@ Response Parameters
- Description: Description
- Parameters: Parameters
Response Example
----------------
.. literalinclude:: samples/template-validate-response.json
:language: javascript
Show resource template
======================
.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name}/template
Shows the template representation for a resource type.
The returned template contains a single resource type. Each
resource property is mapped to a template parameter and each
resource attribute is mapped to a template output.
You can use these templates as a starting place for creating
customized, template-based resources or as examples of using the
particular resource in another template.
Use the ``template_type`` query parameter to specify the resource
template type. Default type is ``cfn``. The ``hot`` template type
is supported. For example:
::
/v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn
Normal response codes: 200
Error response codes:404,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Outputs: Outputs
- HeatTemplateFormatVersion: HeatTemplateFormatVersion
- Resources: Resources
- Parameters: Parameters
Response Example
----------------
.. literalinclude:: samples/resource-type-template-response.json
:language: javascript
Get stack template
==================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template
Gets a template for a stack.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- outputs: outputs
- heat_template_version: heat_template_version
- description: description
- parameters: parameters
- resources: resources
Response Example
----------------
.. literalinclude:: samples/template-show-response.json
:language: javascript
Show resource schema
====================
.. rest_method:: GET /v1/{tenant_id}/resource_types/{type_name}
Shows the interface schema for a resource type.
A schema describes the properties that can be set on the resource,
their types, constraints, descriptions, and default values.
Additionally, the response shows the resource attributes and their
descriptions.
Normal response codes: 200
Error response codes:401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
- with_description: with_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: description
- required: required
- update_allowed: update_allowed
- support_status: support_status
- attributes: attributes
- type: type
- properties: properties
- description: resource_description
- resource_type: resource_type
Response Example
----------------
.. literalinclude:: samples/resource-schema-response.json
:language: javascript

View File

@ -243,9 +243,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
@ -293,6 +293,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- files: files
- disable_rollback: disable_rollback
- parameters: parameters
@ -301,9 +304,6 @@ Request Parameters
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
@ -327,6 +327,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- files: files
- parameters: parameters
- tags: tags
@ -334,9 +337,6 @@ Request Parameters
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
@ -366,9 +366,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Abandon stack
@ -390,9 +390,9 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Example
----------------
@ -415,6 +415,7 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- files: files
- disable_rollback: disable_rollback
- parameters: parameters
@ -422,7 +423,6 @@ Request Parameters
- adopt_stack_data: adopt_stack_data
- environment: environment
- timeout_mins: timeout_mins
- tenant_id: tenant_id
Request Example
---------------
@ -438,3 +438,41 @@ Response Parameters
- id: id
- links: links
- stack: stack
Get stack template
==================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template
Gets a template for a stack.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- outputs: outputs
- heat_template_version: heat_template_version
- description: description
- parameters: parameters
- resources: resources
Response Example
----------------
.. literalinclude:: samples/template-show-response.json
:language: javascript