openstack/cinder
Code Issues Proposed changes
34c56b4fa1
cinder/api-ref/v2/source/volumes-v2-snapshots.inc
Sheel Rana 8659ff0ef5 WADL to RST migration in cinder tree 
This patch is for converting API Reference to RST and host it
in the Cinder tree.
This patch contains all the RST for cinder to bring over to their
repos to begin building API reference information from within.
This contains .inc files which have all the contents of the .rst files
but are grouped together for easier editing

This is the results of the RST conversion from WADL. It creates a
single index plus a bunch of included files which represent sections
of the API.

Cleaning task will be done once this part is merged.

As we have removed XML API support in Newton release, we need to
remove XML from API reference as well.

But we still have installations which are using XML.
So implementation plan is to first merge this patch in Newton release
keeping XML for now, then I will backport same to stable branches.
After that I will remove same from Newton release to match API
reference with actual API implementation.

Implements: bp api-reference-to-rst
Change-Id: I865ac922538bfa5bd45c24eb4bc49f5e966dc811
2016-05-12 19:07:30 +00:00

360 lines
6.9 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
============================
Volume snapshots (snapshots)
============================
A snapshot is a point-in-time copy of the data that a volume
contains.
When you create, list, or delete snapshots, these status values are
possible:
**Snapshot statuses**
+----------------+-------------------------------------+
| Status | Description |
+----------------+-------------------------------------+
| creating | The snapshot is being created. |
+----------------+-------------------------------------+
| available | The snapshot is ready to use. |
+----------------+-------------------------------------+
| deleting | The snapshot is being deleted. |
+----------------+-------------------------------------+
| error | A snapshot creation error occurred. |
+----------------+-------------------------------------+
| error_deleting | A snapshot deletion error occurred. |
+----------------+-------------------------------------+
List snapshots with details
===========================
.. rest_method:: GET /v2/{tenant_id}/snapshots/detail
Lists all Block Storage snapshots, with details, that the tenant can access.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
- description: description
- created_at: created_at
- name: name
- volume_id: volume_id
- os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
- size: size
- id: id
- metadata: metadata
Response Example
----------------
.. literalinclude:: ./samples/snapshots-list-detailed-response.json
:language: javascript
Create snapshot
===============
.. rest_method:: POST /v2/{tenant_id}/snapshots
Creates a volume snapshot, which is a point-in-time, complete copy of a volume. You can create a volume from a snapshot.
Error response codes:202,
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- volume_id: volume_id
- force: force
- description: description
- name: name
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/snapshot-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- name: name
- snapshot: snapshot
- volume_id: volume_id
- metadata: metadata
- id: id
- size: size
List snapshots
==============
.. rest_method:: GET /v2/{tenant_id}/snapshots
Lists all Block Storage snapshots, with summary information, that the tenant can access.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- name: name
- volume_id: volume_id
- metadata: metadata
- id: id
- size: size
Response Example
----------------
.. literalinclude:: ./samples/snapshots-list-response.json
:language: javascript
Show snapshot metadata
======================
.. rest_method:: GET /v2/{tenant_id}/snapshots/{snapshot_id}/metadata
Shows metadata for a snapshot.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- snapshot_id: snapshot_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
- description: description
- created_at: created_at
- name: name
- snapshot: snapshot
- volume_id: volume_id
- os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
- size: size
- id: id
- metadata: metadata
Response Example
----------------
.. literalinclude:: ./samples/snapshot-metadata-show-response.json
:language: javascript
Update snapshot metadata
========================
.. rest_method:: PUT /v2/{tenant_id}/snapshots/{snapshot_id}/metadata
Updates metadata for a snapshot.
Replaces metadata items that match keys. Does not modify items that
are not in the request.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- metadata: metadata
- tenant_id: tenant_id
- snapshot_id: snapshot_id
Request Example
---------------
.. literalinclude:: ./samples/snapshot-metadata-update-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: ./samples/snapshot-metadata-update-response.json
:language: javascript
Show snapshot details
=====================
.. rest_method:: GET /v2/{tenant_id}/snapshots/{snapshot_id}
Shows details for a snapshot.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- snapshot_id: snapshot_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- os-extended-snapshot-attributes:progress: os-extended-snapshot-attributes:progress
- description: description
- created_at: created_at
- name: name
- snapshot: snapshot
- volume_id: volume_id
- os-extended-snapshot-attributes:project_id: os-extended-snapshot-attributes:project_id
- size: size
- id: id
- metadata: metadata
Response Example
----------------
.. literalinclude:: ./samples/snapshot-show-response.json
:language: javascript
Update snapshot
===============
.. rest_method:: PUT /v2/{tenant_id}/snapshots/{snapshot_id}
Updates a snapshot.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- snapshot: snapshot
- description: description
- name: name
- tenant_id: tenant_id
- snapshot_id: snapshot_id
Request Example
---------------
.. literalinclude:: ./samples/snapshot-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- name: name
- snapshot: snapshot
- volume_id: volume_id
- metadata: metadata
- id: id
- size: size
Response Example
----------------
.. literalinclude:: ./samples/snapshot-update-response.json
:language: javascript
Delete snapshot
===============
.. rest_method:: DELETE /v2/{tenant_id}/snapshots/{snapshot_id}
Deletes a snapshot.
Error response codes:202,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- snapshot_id: snapshot_id
View Git Blame Copy Permalink