diff --git a/api-ref/source/v1/stack-outputs.inc b/api-ref/source/v1/stack-outputs.inc new file mode 100644 index 0000000000..daf43f4a6c --- /dev/null +++ b/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 diff --git a/api-ref/source/v1/stack-resources.inc b/api-ref/source/v1/stack-resources.inc index f0216476e0..d2da463dcc 100644 --- a/api-ref/source/v1/stack-resources.inc +++ b/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. - - - diff --git a/api-ref/source/v1/stack-snapshots.inc b/api-ref/source/v1/stack-snapshots.inc new file mode 100644 index 0000000000..df4633f79f --- /dev/null +++ b/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 diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc index c5cdc71997..8b6c01cf0f 100644 --- a/api-ref/source/v1/stacks.inc +++ b/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 -============= +Error response codes:201,500,409,401,400, -.. 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, - - -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 + - links: links + - stack_status_reason: stack_status_reason + - stack_name: stack_name - 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 - - - - + - 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} + +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, -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 -------- +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,13 +273,43 @@ 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 + - 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 @@ -454,8 +322,8 @@ Deletes a stack and its snapshots. Error response codes:500,404,204,401,400, -Request -------- +Request Parameters +------------------ .. rest_parameters:: parameters.yaml @@ -464,181 +332,36 @@ Request - stack_id: stack_id +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. - - - - - -Show output -=========== - -.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key} - -Shows details for a stack output. +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: +Error response codes:404,500,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 +.. literalinclude:: samples/stack-abandon-response.json :language: javascript - - -List stack data -=============== - -.. rest_method:: GET /v1/{tenant_id}/stacks - -Lists active stacks. - - -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 - - -Response 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 - - - -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 - :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 - - -