Snapshots#

A snapshot is a point-in-time copy of the data that a volume contains.

When you make an API call to create, list, or delete snapshots, the following status values are possible:

  • CREATING: The snapshot is being created.

  • AVAILABLE: The snapshot is ready for use.

  • DELETING: The snapshot is being deleted.

  • ERROR: An error occurred during snapshot creation.

  • ERROR_DELETING: An error occurred during snapshot deletion.

Create a snapshot#

POST /v1/{tenant_id}/snapshots

This operation creates a snapshot.

A snapshot is a point-in-time copy of the volume. You must flush all writes to the volume before you create a snapshot. To do so, either unmount any file systems on the volume or detach the volume.

Snapshots are incremental, so each time that you create a snapshot, the incremental changes for the new snapshot are appended to the previous snapshot, which is still available. Note that you can create a volume from the snapshot if desired.

The os-extended-snapshot-attributes:progress field in the response body shows the snapshot progress.

When the POST operation returns the 201 response code, the snapshot is complete.

For more information about snapshots, see Create and Use Cloud Block Storage Snapshots.

Request parameters#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

The request has the following body parameters.

Name

Type

Description

snapshot

String (Required)

A partial representation of a snapshot used in the creation process.

snapshot.volume_id

Uuid (Required)

The ID of the volume to snapshot.

snapshot.force

Boolean

[True/False] Indicate whether to snapshot, even if the volume is attached. The default is False.

snapshot.display_name

String

Name of the snapshot. The default is None.

snapshot.display_description

String

Description of snapshot. The default is None.

Request example#

The following XML example creates a snapshot.

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.rackspace.com/volume/api/v1"
          name="snap-001"
          display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          force="true" />

The following JSON example creates a snapshot.

{
    "snapshot": {
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "force": true
     }
}

Response examples#

The following example shows the XML response for creating a snapshot.

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.rackspace.com/volume/api/v1"
          created_at="2014-01-28T16:56:56.000000"
          display_name="snap-001"
          display_description="Daily backup"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          metadata="null"
          os-extended-snapshot-attributes:progress="25.39%"
          os-extended-snapshot-attributes:project_id="696059"
          size="100"
          status="creating"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c" />

The following example shows the JSON response for creating a snapshot.

{
    "snapshot": {
        "created_at": "2014-01-28T16:56:56.000000",
        "display_description": "Daily backup",
        "display_name": "snap-001",
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "metadata": {},
        "os-extended-snapshot-attributes:progress": "25.39%",
        "os-extended-snapshot-attributes:project_id": "123456",
        "size": 100,
        "status": "creating",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"
     }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description
201 |Created |The request has been
|fulfilled and a resource
|was created.
429 |SnapshotQuotaExceeded |Snapshot quota limit has
|been exceeded per
|volume.

Retrieve snapshots#

GET /v1/{tenant_id}/snapshots

This operation retrieves summary information for all Cloud Block Storage snapshots that the tenant who submits the request can access.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving summary information about snapshots.

<?xml version="1.0" encoding="UTF-8"?>
<snapshots xmlns="http://docs.rackspace.com/volume/api/v1">
    <snapshot id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
              display_name="snap-001"
              display_description="Daily backup"
              volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
              status="available"
              size="100"
              created_at="2012-02-29T03:50:07Z" />
    <snapshot id="e479997c-650b-40a4-9dfe-77655818b0d2"
              display_name="snap-002"
              dislay_description="Weekly backup"
              volume_id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
              status="available"
              size="100"
              created_at="2012-03-19T01:52:47Z" />
</snapshots>

The following example shows the JSON response for retrieving summary information about snapshots.

{
    "snapshots": [
        {
            "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
            "display_name": "snap-001",
            "display_description": "Daily backup",
            "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "status": "available",
            "size": 100,
            "created_at": "2012-02-29T03:50:07Z"
        },
        {
            "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
            "display_name": "snap-002",
            "display_description": "Weekly backup",
            "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "status": "available",
            "size": 100,
            "created_at": "2012-03-19T01:52:47Z"
        }
    ]
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Retrieve snapshots (detailed)#

GET /v1/{tenant_id}/snapshots/detail

This operation retrieves detailed information for all Cloud Block Storage snapshots that the tenant who submits the request can access.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving the snapshots in detail.

<?xml version='1.0' encoding='UTF-8'?>
<snapshots
    xmlns="http://docs.rackspace.com/volume/api/v1">
    <snapshot status="available" description="Daily backup"
        created_at="2013-02-25 07:30:12"
        volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="30"
        id="43f20e0e-2c2c-4770-9d4e-c3d769ae5470" name="snap-001"
        os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-extended-snapshot-attributes:progress="100%">
        <metadata/>
    </snapshot>
    <snapshot status="available" description="Weekly backup"
        created_at="2013-02-25 07:20:38"
        volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
        id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002"
        os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-extended-snapshot-attributes:progress="100%">
        <metadata/>
    </snapshot>
</snapshots>

The following example shows the JSON response for retrieving the snapshots in detail.

{
    "snapshots": [
        {
            "status": "available",
            "os-extended-snapshot-attributes:progress": "100%",
            "description": "Daily backup",
            "created_at": "2013-02-25T07:30:12.000000",
            "metadata": {},
            "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 30,
            "id": "43f20e0e-2c2c-4770-9d4e-c3d769ae5470",
            "name": "snap-001"
        },
        {
            "status": "available",
            "os-extended-snapshot-attributes:progress": "100%",
            "description": "Weekly backup",
            "created_at": "2013-02-25T07:20:38.000000",
            "metadata": {},
            "volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
            "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 1,
            "id": "e820db06-58b5-439d-bac6-c01faa3f6499",
            "name": "snap-002"
        }
    ]
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Retrieve details for a snapshot#

GET /v1/{tenant_id}/snapshots/{snapshot_id}

This operation retrieves details for the specified snapshot.

Note

The os-extended-snapshot-attributes:progress field in the response body shows snapshot progress. See the following examples.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{snapshot_id}

String

The unique identifier of an existing snapshot.

This operation does not accept a request body.

Response examples#

The following example shows the XML response for retrieving details for the specified snapshot.

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.rackspace.com/volume/api/v1"
          created_at="2014-01-28T16:56:56.000000"
          display_name="snap-001"
          display_description="Daily backup"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          metadata="null"
          os-extended-snapshot-attributes:progress="25.39%"
          os-extended-snapshot-attributes:project_id="696059"
          size="100"
          status="creating"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c" />

The following example shows the JSON response for retrieving details for the specified snapshot.

{
    "snapshot": {
        "created_at": "2014-01-28T16:56:56.000000",
        "display_description": "Daily backup",
        "display_name": "snap-001",
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "metadata": {},
        "os-extended-snapshot-attributes:progress": "25.39%",
        "os-extended-snapshot-attributes:project_id": "123456",
        "size": 100,
        "status": "creating",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"
     }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Update a snapshot#

PUT /v1/{tenant_id}/snapshots/{snapshot_id}

This operation updates a specified snapshot.

Request parameters#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{snapshot_id}

String

The unique identifier of an existing snapshot.

The request has the following body parameters.

Name

Type

Description

snapshot

String (Required)

Information about the snapshot.

snapshot.display_description

String

A description of the snapshot.

snapshot.display_name

String

The name of the snapshot.

Request examples#

The following XML example updates a snapshot.

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.rackspace.com/volume/api/v1"
          display_name="snap-001"
          display_description="This is yet, another snapshot."/>

The following JSON example updates a snapshot.

{
    "snapshot":{
        "display_name":"snap-001",
        "display_description":"This is yet, another snapshot."
    }
}

Response examples#

The following example shows the XML response for updating a snapshot.

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
    xmlns:os-extended-snapshot-attributes="http://docs.rackspace.com/volume/api/v1"
    status="available"
    display_description="This is yet, another snapshot"
    created_at="2013-02-20T08:11:34.000000"
    volume_id="2402b902-0b7a-458c-9c07-7435a826f794"
    size="1"
    id="4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2"
    display_name="vol-001"
    os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
    os-extended-snapshot-attributes:progress="100%">
    <metadata/>
</snapshot>

The following example shows the JSON response for updating a snapshot.

{
    "snapshot":{
        "created_at":"2013-02-20T08:11:34.000000",
        "display_description":"This is yet, another snapshot",
        "display_name":"vol-001",
        "id":"4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2",
        "size":1,
        "status":"available",
        "volume_id":"2402b902-0b7a-458c-9c07-7435a826f794"
    }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Delete a snapshot#

DELETE /v1/{tenant_id}/snapshots/{snapshot_id}

This operation deletes a snapshot.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{snapshot_id}

String

The unique identifier of an existing snapshot.

This operation does not accept a request body.

Response#

This operation does not return a response body.

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

202

Accepted

The request has been fulfilled and a resource was created.

Retrieve metadata for a snapshot#

GET /v1/{tenant_id}/snapshots/{snapshot_id}/metadata

This operation retrieves the metadata for the specified snapshot.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{snapshot_id}

String

The unique identifier of an existing snapshot.

This operation does not accept a request body.

Response example#

The following example shows the JSON response for retrieving the metadata for a specified snapshot.

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "0%",
        "description": null,
        "created_at": "2014-05-06T17:59:52.000000",
        "metadata": {
            "key": "v1"
        },
        "volume_id": "ebd80b99-bc3d-4154-9d28-5583baa80580",
        "os-extended-snapshot-attributes:project_id": "7e0105e19cd2466193729ef78b604f79",
        "size": 10,
        "id": "dfcd17fe-3b64-44ba-b95f-1c9c7109ef95",
        "name": "my-snapshot"
    }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success