Block Storage API v1

Service enables instant creation of configurable or storage volumes and there cloud server attachments. It is already know under OpenStack as Cinder.

API versions

GET

List API versions

Lists information about all Block Storage API versions.

Normal response codes

200, 300

{
    "versions": [
        {
            "status": "CURRENT",
            "updated": "2012-01-04T11:33:21Z",
            "id": "v1.0",
            "links": [
                {
                    "href": "https://volume.fr1.cloudwatt.com/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "updated": "2012-11-21T11:33:21Z",
            "id": "v2.0",
            "links": [
                {
                    "href": "https://volume.fr1.cloudwatt.com/v2/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET

/v1

Show API v1 details

Shows details for Block Storage API v1.

Normal response codes

200, 203

{
    "version": {
        "status": "CURRENT",
        "updated": "2012-01-04T11:33:21Z",
        "media-types": [
            {
                "base": "application/xml",
                "type": "application/vnd.openstack.volume+xml;version=1"
            },
            {
                "base": "application/json",
                "type": "application/vnd.openstack.volume+json;version=1"
            }
        ],
        "id": "v1.0",
        "links": [
            {
                "href": "https://volume.fr1.cloudwatt.com/v1/",
                "rel": "self"
            },
            {
                "href": "http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf",
                "type": "application/pdf",
                "rel": "describedby"
            },
            {
                "href": "http://docs.rackspacecloud.com/servers/api/v1.1/application.wadl",
                "type": "application/vnd.sun.wadl+xml",
                "rel": "describedby"
            }
        ]
    }
}

This operation does not accept a request body.

Volumes

POST

/v1/{tenant_id}/volumes

Create volume

Creates a volume.

Normal response codes

201

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume	plain	csapi:string	A partial representation of a volume used in the creation process.

{
    "volume": {
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        display_name="vol-001"
        display_description="Another volume."
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>

{
    "volume": {
        "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1",
        "bootable": "false",
        "snapshot_id": null,
        "attachments": [],
        "created_at": "2012-02-14T20:53:07Z"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        display_name="vol-001"
        display_description="Another volume."
        status="active"
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1"
        bootable="false"
        created_at="2012-02-14T20:53:07Z">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>

GET

/v1/{tenant_id}/volumes

List volumes

Lists simple volume entities.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volumes xmlns="http://docs.openstack.org/volume/api/v1">
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
            display_name="vol-001"
            display_description="Another volume."
            status="active"
            size="30"
            volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
            availability_zone="us-east1"
            created_at="2012-02-14T20:53:07Z">
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
            display_name="vol-002"
            display_description="Yet another volume."
            status="active"
            size="25"
            volume_type="96c3bda7-c82a-4f50-be73-ca7621794835"
            availability_zone="us-east2"
            created_at="2012-03-15T19:10:03Z" />
</volumes>

This operation does not accept a request body.

GET

/v1/{tenant_id}/volumes/detail

List volumes (detailed)

Lists details for volume entities.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volumes xmlns="http://docs.openstack.org/volume/api/v1">
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
            display_name="vol-001"
            display_description="Another volume."
            status="active"
            size="30"
            volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
            availability_zone="us-east1"
            created_at="2012-02-14T20:53:07Z">
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
            display_name="vol-002"
            display_description="Yet another volume."
            status="active"
            size="25"
            volume_type="96c3bda7-c82a-4f50-be73-ca7621794835"
            availability_zone="us-east2"
            created_at="2012-03-15T19:10:03Z" />
</volumes>

This operation does not accept a request body.

GET

/v1/{tenant_id}/volumes/{volume_id}

Show volume information

Shows information about a specified volume.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

{
    "volume": {
        "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1",
        "bootable": "false",
        "snapshot_id": null,
        "attachments": [],
        "created_at": "2012-02-14T20:53:07Z"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        display_name="vol-001"
        display_description="Another volume."
        status="active"
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1"
        bootable="false"
        created_at="2012-02-14T20:53:07Z">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>

This operation does not accept a request body.

DELETE

/v1/{tenant_id}/volumes/{volume_id}

Delete volume

Deletes a specified volume.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

This operation does not accept a request body and does not return a response body.

Volume types

GET

/v1/{tenant_id}/types

List volume types

Request a list of volume types.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.

{
    "volume_types": [
        {
            "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "name": "vol-type-001",
            "extra_specs": {
                "capabilities": "gpu"
            }
        },
        {
            "id": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "name": "vol-type-002",
            "extra_specs": {}
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_types xmlns="http://docs.openstack.org/volume/api/v1">
    <volume_type id="289da7f8-6440-407c-9fb4-7db01ec49164"
                 name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
    </volume_type>
    <volume_type id="96c3bda7-c82a-4f50-be73-ca7621794835"
                 name="vol-type-002" />
</volume_types>

This operation does not accept a request body.

POST

/v1/{tenant_id}/types

Create volume type

Creates a volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume_type	plain	csapi:string	A partial representation of a volume type used in the creation process.

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
        name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
</volume_type>

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

GET

/v1/{tenant_id}/types/{volume_type_id}

Show volume type information

Shows information about a specified volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier of an existing volume type.

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

This operation does not accept a request body.

DELETE

/v1/{tenant_id}/types/{volume_type_id}

Delete volume type

Deletes a specified volume type.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier of an existing volume type.

This operation does not accept a request body and does not return a response body.

Snapshots

POST

/v1/{tenant_id}/snapshots

Create snapshot

Creates a snapshot.

Normal response codes

201

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
snapshot	plain	csapi:string	A partial representation of a snapshot used in the creation process.

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

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

{
    "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": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.openstack.org/volume/api/v1"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          status="available"
          size="30"
          created_at="2012-02-29T03:50:07Z" />

GET

/v1/{tenant_id}/snapshots

List snapshots

Lists simple snapshot entities.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.

{
    "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": 30,
            "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": 25,
            "created_at": "2012-03-19T01:52:47Z"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshots xmlns="http://docs.openstack.org/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="30"
              created_at="2012-02-29T03:50:07Z" />
    <snapshot id="e479997c-650b-40a4-9dfe-77655818b0d2"
              display_name="snap-002"
              display_description="Weekly backup"
              volume_id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
              status="available"
              size="25"
              created_at="2012-03-19T01:52:47Z" />
</snapshots>

This operation does not accept a request body.

GET

/v1/{tenant_id}/snapshots/detail

List snapshots (detailed)

Lists details for snapshot entities.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.

{
    "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": 30,
            "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": 25,
            "created_at": "2012-03-19T01:52:47Z"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshots xmlns="http://docs.openstack.org/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="30"
              created_at="2012-02-29T03:50:07Z" />
    <snapshot id="e479997c-650b-40a4-9dfe-77655818b0d2"
              display_name="snap-002"
              display_description="Weekly backup"
              volume_id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
              status="available"
              size="25"
              created_at="2012-03-19T01:52:47Z" />
</snapshots>

This operation does not accept a request body.

GET

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

Show snapshot information

Shows information about a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
    "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": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.openstack.org/volume/api/v1"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          status="available"
          size="30"
          created_at="2012-02-29T03:50:07Z" />

This operation does not accept a request body.

DELETE

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

Delete snapshot

Deletes a specified snapshot.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

This operation does not accept a request body and does not return a response body.

GET

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

Show snapshot metadata

Shows the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing 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"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
    xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1"
    status="available" description="None"
    created_at="2014-05-06 17:59:52"
    volume_id="ebd80b99-bc3d-4154-9d28-5583baa80580" size="10"
    id="dfcd17fe-3b64-44ba-b95f-1c9c7109ef95" name="my-snapshot"
    os-extended-snapshot-attributes:project_id="7e0105e19cd2466193729ef78b604f79"
    os-extended-snapshot-attributes:progress="0%">
    <metadata>
        <meta key="key">v1</meta>
    </metadata>
</snapshot>

This operation does not accept a request body.

PUT

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

Update snapshot metadata

Updates the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	csapi:UUID	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to set or unset for the snapshot. To unset a metadata key value, specify only the key name. To set a metadata key value, specify the key and value pair. The Block Storage server does not respect case-sensitive key names. For example, if you specify both `"key": "v1"` and `"KEY": "V1"`, the server sets and returns only the `KEY` key and value pair.

{
    "metadata": {
        "key": "v1"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
    <meta key="key">v1</meta>
</metadata>

{
    "metadata": {
        "key": "v1"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata xmlns="http://docs.openstack.org/compute/api/v1.1">
    <meta key="key">v1</meta>
</metadata>

The OpenStack project is provided under the Apache 2.0 license.
The original OpenStack Documentation is available on: docs.openstack.org