Browse Source

Split stack api-ref doc into three files

This patch splits the stacks.inc file into three files so that we can
patch them separately. The original file contains API calls about
stacks, stack snapshots and stack outputs, however, the latter two
have every right to be documented separately.

Change-Id: I3e3b71c914046939cd816c79359601e91791cf82
changes/81/356981/1
tengqm 6 years ago
parent
commit
77927765a9
  1. 78
      api-ref/source/v1/stack-outputs.inc
  2. 64
      api-ref/source/v1/stack-resources.inc
  3. 173
      api-ref/source/v1/stack-snapshots.inc
  4. 665
      api-ref/source/v1/stacks.inc

78
api-ref/source/v1/stack-outputs.inc

@ -0,0 +1,78 @@
.. -*- rst -*-
=============
Stack Outputs
=============
List outputs
============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs
Lists outputs for a stack.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- output_value: output_value
- output_error: output_error
- description: description
- output_key: output_key
Response Example
----------------
.. literalinclude:: samples/stack-outputs-list-response.json
:language: javascript
Show output
===========
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key}
Shows details for a stack output.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- output_key: output_key
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- output_value: output_value
- output_error: output_error
- description: description
- output_key: output_key
Response Example
----------------
.. literalinclude:: samples/stack-show-output-response.json
:language: javascript

64
api-ref/source/v1/stack-resources.inc

@ -4,9 +4,6 @@
Stack resources
===============
Show resource metadata
======================
@ -18,9 +15,8 @@ Shows metadata for a resource.
Normal response codes: 200
Error response codes:
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -29,9 +25,6 @@ Request
- tenant_id: tenant_id
- stack_id: stack_id
Response Example
----------------
@ -39,8 +32,6 @@ Response Example
:language: javascript
Show resource data
==================
@ -52,9 +43,8 @@ Shows data for a resource.
Normal response codes: 200
Error response codes:404,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -63,7 +53,6 @@ Request
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
@ -81,8 +70,6 @@ Response Parameters
- physical_resource_id: physical_resource_id
- resource_type: resource_type
Response Example
----------------
@ -90,11 +77,6 @@ Response Example
:language: javascript
List resources
==============
@ -104,13 +86,11 @@ 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
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -144,18 +124,35 @@ Response Parameters
- 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
@ -175,9 +172,8 @@ they return a 400 error code.
Normal response codes: 200
Error response codes:
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -186,13 +182,7 @@ Request
- tenant_id: tenant_id
- stack_id: stack_id
Response Example
----------------
This operation does not return a response body.

173
api-ref/source/v1/stack-snapshots.inc

@ -0,0 +1,173 @@
.. -*- rst -*-
===============
Stack Snapshots
===============
Snapshot stack
==============
.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- name: name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
.. literalinclude:: samples/stack-snapshot-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- data: data
- id: id
Response Example
----------------
.. literalinclude:: samples/stack-snapshot-response.json
:language: javascript
Show snapshot
=============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
Shows details for a snapshot.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- snapshot: snapshot
- template: template
- project_id: project_id
- data: data
- id: id
- resources: resources
Response Example
----------------
.. literalinclude:: samples/stack-show-snapshot-response.json
:language: javascript
List snapshots
==============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
Lists snapshots for a stack.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- snapshots: snapshots
- data: data
- id: id
Response Example
----------------
.. literalinclude:: samples/stack-snapshots-list-response.json
:language: javascript
Delete snapshot
===============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
Deletes a stack snapshot.
Error response codes:204,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
Restore snapshot
================
.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore
Restores a stack snapshot.
You can restore only active stacks from a snapshot. You must
recreate deleted stacks.
Error response codes:202,
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id

665
api-ref/source/v1/stacks.inc

@ -4,122 +4,45 @@
Stacks
======
Create stack
============
.. rest_method:: POST /v1/{tenant_id}/stacks
Creates a stack.
Abandon stack
=============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon
Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources.
This method can be disabled from the server side. If it is
disabled, this call throws an exception.
Normal response codes: 200
Error response codes:404,500,401,400,
Error response codes:201,500,409,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- files: files
- disable_rollback: disable_rollback
- parameters: parameters
- tags: tags
- stack_name: stack_name
- environment: environment
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
Response Example
----------------
.. literalinclude:: samples/stack-abandon-response.json
.. literalinclude:: samples/stack-create-request.json
:language: javascript
Show snapshot
=============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
Shows details for a snapshot.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- snapshot: snapshot
- template: template
- project_id: project_id
- data: data
- id: id
- resources: resources
Response Example
----------------
.. literalinclude:: samples/stack-show-snapshot-response.json
:language: javascript
Delete snapshot
===============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
Deletes a stack snapshot.
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
- links: links
- stack: stack
Preview stack
@ -129,13 +52,11 @@ Preview stack
Previews a stack.
Normal response codes: 200
Error response codes:500,409,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -152,8 +73,6 @@ Request Example
.. literalinclude:: samples/stack-create-request.json
:language: javascript
Response Parameters
-------------------
@ -176,8 +95,6 @@ Response Parameters
- resources: resources
- template_description: template_description
Response Example
----------------
@ -185,160 +102,93 @@ Response Example
:language: javascript
List stacks
===========
.. rest_method:: GET /v1/{tenant_id}/stacks
Restore snapshot
================
.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore
Restores a stack snapshot.
You can restore only active stacks from a snapshot. You must
recreate deleted stacks.
Error response codes:202,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- snapshot_id: snapshot_id
List outputs
============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs
Lists outputs for a stack.
Lists active stacks.
Normal response codes: 200
Error response codes:
Error response codes:500,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- id: id
- status: status
- name: name
- action: action
- tenant: tenant
- username: username
- owner_id: owner_id
- limit: limit
- marker: marker
- show_deleted: show_deleted
- show_nested: show_nested
- sort_keys: sort_keys
- 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
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- output_value: output_value
- output_error: output_error
- description: description
- output_key: output_key
Response Example
----------------
.. literalinclude:: samples/stack-outputs-list-response.json
:language: javascript
Preview stack update
====================
.. rest_method:: PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview
Previews an update for a stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- files: files
- parameters: parameters
- tags: tags
- environment: environment
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- links: links
- stack_status_reason: stack_status_reason
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
.. literalinclude:: samples/stack-update-request.json
:language: javascript
- 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
Response Example
----------------
.. literalinclude:: samples/stack-update-preview-response.json
.. literalinclude:: samples/stacks-list-response.json
:language: javascript
Find stack
==========
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}
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:
::
Finds the canonical URL for a stack.
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
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,
Error response codes:302,404,500,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
Show stack details
==================
@ -346,13 +196,11 @@ Show stack details
Shows details for a stack.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -360,7 +208,6 @@ Request
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
@ -386,8 +233,6 @@ Response Parameters
- stack_user_project_id: stack_user_project_id
- template_description: template_description
Response Example
----------------
@ -395,12 +240,6 @@ Response Example
:language: javascript
Update stack
============
@ -410,9 +249,8 @@ Updates a stack.
Error response codes:404,202,500,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -435,210 +273,95 @@ Request Example
:language: javascript
Preview stack update
====================
.. rest_method:: PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview
Previews an update for a stack.
Normal response codes: 200
Error response codes:
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
Delete stack
============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Deletes a stack and its snapshots.
Error response codes:500,404,204,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- files: files
- parameters: parameters
- tags: tags
- environment: environment
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
.. literalinclude:: samples/stack-update-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: samples/stack-update-preview-response.json
:language: javascript
Delete stack
============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Deletes a stack and its snapshots.
Show output
===========
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key}
Shows details for a stack output.
Normal response codes: 200
Error response codes:
Error response codes:500,404,204,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
- output_key: output_key
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- output_value: output_value
- output_error: output_error
- description: description
- output_key: output_key
Response Example
----------------
.. literalinclude:: samples/stack-show-output-response.json
:language: javascript
Abandon stack
=============
List stack data
===============
.. rest_method:: DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon
.. rest_method:: GET /v1/{tenant_id}/stacks
Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources.
Lists active stacks.
This method can be disabled from the server side. If it is
disabled, this call throws an exception.
Normal response codes: 200
Error response codes:500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- id: id
- status: status
- name: name
- action: action
- tenant: tenant
- username: username
- owner_id: owner_id
- limit: limit
- marker: marker
- show_deleted: show_deleted
- show_nested: show_nested
- sort_keys: sort_keys
- 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
Error response codes:404,500,401,400,
Response Parameters
-------------------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- 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
- tenant_id: tenant_id
- stack_id: stack_id
Response Example
----------------
.. literalinclude:: samples/stacks-list-response.json
:language: javascript
Create stack
============
.. rest_method:: POST /v1/{tenant_id}/stacks
Creates a stack.
Error response codes:201,500,409,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- files: files
- disable_rollback: disable_rollback
- parameters: parameters
- tags: tags
- stack_name: stack_name
- environment: environment
- template_url: template_url
- template: template
- timeout_mins: timeout_mins
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: samples/stack-create-request.json
.. literalinclude:: samples/stack-abandon-response.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: id
- links: links
- stack: stack
Adopt stack
===========
@ -648,9 +371,8 @@ Creates a stack from existing resources.
Error response codes:201,500,409,401,400,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
@ -669,8 +391,6 @@ Request Example
.. literalinclude:: samples/stack-adopt-request.json
:language: javascript
Response Parameters
-------------------
@ -679,144 +399,3 @@ Response Parameters
- id: id
- links: links
- stack: stack
Find stack
==========
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}
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.
Error response codes:302,404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
Snapshot stack
==============
.. rest_method:: POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Request Example
---------------
.. literalinclude:: samples/stack-snapshot-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- data: data
- id: id
Response Example
----------------
.. literalinclude:: samples/stack-snapshot-response.json
:language: javascript
List snapshots
==============
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
Lists snapshots for a stack.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- stack_name: stack_name
- tenant_id: tenant_id
- stack_id: stack_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- status_reason: status_reason
- creation_time: creation_time
- snapshots: snapshots
- data: data
- id: id
Response Example
----------------
.. literalinclude:: samples/stack-snapshots-list-response.json
:language: javascript

Loading…
Cancel
Save