docs.rackspace.com/api

(1)

(2)

Rackspace Cloud Block Storage Getting Started Guide

API v1 (2015-07-27)

This document is intended for software developers interested in developing applications using the Rackspace Cloud Block Storage Ap-plication Programming Interface (API). The document is for informational purposes only and is provided “AS IS.”

RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR COM-PLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND PROD-UCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE WITH-OUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT AS SET FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO LIABILITY WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any license to patents, trademarks, copyrights, or other intellectual property.

Rackspace®, Rackspace logo and Fanatical Support® are registered service marks of Rackspace US, Inc. All other product names and trademarks used in this document are for identification purposes only and are property of their respective owners.

(3)

List of Tables

2.1. cURL command-line options ... 3 3.1. Cloud Block Storage regionalized service endpoints ... 5

(5)

List of Examples

2.1. cURL authentication request: JSON ... 4

4.1. cURL authentication request: JSON ... 6

4.2. Authenticate response with partial service catalog showing cloudBlockStorage: JSON ... 7

4.3. Create a volume: cURL ... 9

4.4. List volumes: cURL ... 10

4.5. Show volume details: cURL ... 11

4.6. Update volume: cURL ... 12

4.7. Delete volume: cURL ... 13

4.8. Create a snapshot: cURL ... 13

4.9. List snapshots: cURL ... 14

4.10. Show snapshot details: cURL ... 15

4.11. Update a snapshot: cURL ... 16

(6)

1. Overview

Rackspace Cloud Block Storage is a block-level storage solution that enables you to mount drives or volumes to your Next Generation Cloud Servers™ and OnMetal™ Cloud Servers. The primary use cases for Cloud Block Storage are to allow you to perform the following tasks:

• Scale your storage independently from your compute resources.

• Use high-performance storage to serve database or I/O-intensive applications. The following options are available for mounting drives or volumes to your server: • The standard-performance option offers extra storage capacity with mountable SATA

drives.

• The high-performance option offers high speed solid state drives (SSDs) for memory-in-tensive applications.

Cloud Block Storage includes the following functionality:

• Cloud Block Storage is an add-on feature to Next Generation Cloud Servers and OnMetal Cloud Servers. You cannot attach Cloud Block Storage volumes to other instances, such as First Generation Cloud Servers.

• Cloud Block Storage is multi-tenant rather than dedicated.

• When volumes are destroyed, Rackspace keeps that disk space unavailable until zeros have been written to the space to ensure that data is not accessible by any other cus-tomers.

• Cloud Block Storage enables you to create snapshots that you can save, list, and restore. This guide provides step-by-step instructions for entering the necessary URLs or commands to use the Cloud Block Storage API. You can find additional details about Cloud Block Stor-age in the Cloud Block StorStor-age Developer Guide at docs.rackspace.com.

For more details about the Cloud Block Storage service, see the information at

www.rackspace.com and the Knowledge Center article Cloud Block Storage Overview. Rackspace welcomes feedback, comments, and bug reports at

[email protected].

Note

Cloud Block Storage is built on the OpenStack Cinder project. For more infor-mation about OpenStack Cinder, see the OpenStack Block Storage API v1 Refer-ence.

(7)

2. Sending requests to the API

You have several options for sending requests through an API:

• Developers and testers might prefer to use the command-line tool cURL. For more infor-mation about cURL, see the cURL website. With cURL, you can send HTTP requests and receive responses back from the command line.

• If you like to use a more graphical interface, the RESTClient for Mozilla Firefox works well for testing commands. For more information, see the Mozilla RESTclient website.

• You can download and install RESTClient, a Java application used to test RESTful web ser-vices. For more information, see the Java application RESTClient website.

This guide uses the API directly with cURL (Chapter 4, “Using the API directly by using cURL” [6]).

2.1. Prerequisites for running examples

To run the examples in this guide, you must have the following prerequisites: • Rackspace Cloud account

To sign up for a Rackspace Cloud account, go to the signup page.

• Rackspace Cloud user name and password, as specified during registration. You also need to know your API key. To find your API key, use the following steps: 1. Log in to the Cloud Control Panel (mycloud.rackspace.com).

2. On the upper-right side of the top navigation pane, click your username. 3. From the menu, select Account Settings.

4. In the Login Details section of the Account Settings page, locate the API Key field and click Show.

5. Copy the value of the API key and paste it into a text editor of your choice. 6. Click Hide to hide the value of the API key.

2.2. Sending API requests by using cURL

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets you to transmit and receive HTTP requests and responses from the command line or a shell script, which enables you to work with the API directly (without using one of the lan-guage-specific APIs). cURL is available for most UNIX system-based environments, Apple Mac OS X, and Microsoft Windows. For more information about cURL, see the cURL web-site.

(8)

The following cURL command-line options are used in this guide to run the examples.

Table 2.1. cURL command-line options

Option Description

-d Sends the specified data in a POST request to the HTTP server. -i Includes the HTTP header in the output.

-H HEADER Specifies an HTTP header in the request. You can specify any number of extra headers.

Precede each header with the -H option.

-s Specifies silent or quiet mode; does not show progress or error messages. If your cURL

command is not generating any output, try replacing the -s option with -i.

-X Specifies the request operation to use when communicating with the HTTP server. The

specified request is used instead of the default operation, which is GET. For example, -X PUT specifies to use the PUT operation.

Note

If you have the tools, you can run the cURL JSON request examples with the fol-lowing option to format the output from cURL: <cURL JSON request example> | python -m json.tool.

2.3. Copying and pasting cURL request examples

into a terminal window

To run the cURL request examples shown in this guide, perform the following actions: 1. Copy each example from the HTML version of this guide and paste it into an ASCII text

editor (for example, vi or TextEdit). You can click on the small document icon to the right of each request example to select it.

2. Modify each example with your required account information and other information, as detailed in this guide.

Note

The carriage returns in the cURL request examples are escaped with a back-slash (\) character. The escape character allows continuation of the com-mand across multiple lines. However, do not include the escape character in the JSON or XML request body within the cURL command.

3. After you are finished modifying the text for the cURL request example with your infor-mation (for example, user name and API key), copy and paste the text into your terminal window.

4. Press Enter to run the cURL command.

Consider the following cURL authentication request JSON example, which is described in detail in Section 4.1, “Generating an authentication token” [6].

(9)

Example 2.1. cURL authentication request: JSON

curl -d \ '{ "auth": { "RAX-KSKEY:apiKeyCredentials": { "username": "yourUserName", "apiKey": "yourApiKey"} } }' \ -H 'Content-Type: application/json' \

'https://identity.api.rackspacecloud.com/v2.0/tokens' | python -m json.tool In the example, the lines that are part of the cURL command syntax have all been escaped with a backslash (\) to indicate that the command continues on the next line:

curl -d \

(... lines within the JSON portion of the message are not shown in this example)

(... the example shows only lines that are part of cURL syntax)

}' \

-H 'Content-Type: application/json' \

'https://identity.api.rackspacecloud.com/v2.0/tokens' | python -m json.tool However, the lines within the JSON portion of the message are not escaped with a back-slash, to avoid issues with the JSON processing:

'{ "auth": { "RAX-KSKEY:apiKeyCredentials": { "username": "yourUserName", "apiKey": "yourApiKey"} } }' \

The final line of the JSON message is escaped, but the backslash lies outside the JSON mes-sage and continues the cURL command to the next line.

Tip

If you have trouble copying and pasting the examples as described, try typing the entire example on one long line, removing all the backslash line-continua-tion characters.

(10)

3. Service access endpoints

The Cloud Block Storage service is a regionalized service. The user of the service is respon-sible for appropriate replication, caching, and overall maintenance of Cloud Block Storage data across regional boundaries to other Cloud Block Storage servers.

The available service access endpoints for Cloud Block Storage are summarized in the fol-lowing table.

To help you decide which regionalized endpoint to use, read the Knowledge Center article about special considerations for choosing a data center at About Regions.

Table 3.1. Cloud Block Storage regionalized service endpoints

Region Endpoint

Chicago (ORD) https://ord.blockstorage.api.rackspacecloud.com/v1/1234/

Dallas/Ft. Worth (DFW) https://dfw.blockstorage.api.rackspacecloud.com/v1/1234/

Northern Virginia (IAD) https://iad.blockstorage.api.rackspacecloud.com/v1/1234/

London (LON) https://lon.blockstorage.api.rackspacecloud.com/v1/1234/

Sydney (SYD) https://syd.blockstorage.api.rackspacecloud.com/v1/1234/

Hong Kong (HKG) https://hkg.blockstorage.api.rackspacecloud.com/v1/1234/

Replace the sample account ID number, 1234, with your actual account number, which is returned as part of the authentication service response.

Your actual account number is located after the final slash (/) in the publicURL field re-turned by the authentication response (see Example 4.2, “Authenticate response with par-tial service catalog showing cloudBlockStorage: JSON” [7]).

(11)

4. Using the API directly by using cURL

The main purpose of this guide is to get you started quickly with Cloud Block Storage. To help you accomplish this goal, this chapter contains simple examples for authentication and some basic Cloud Block Storage requests that you will commonly use. Example requests are provided in cURL, followed by the response.

For more information about all Cloud Block Storage operations, see the Cloud Block Stor-age Developer Guide.

4.1. Generating an authentication token

Your first step must always be to generate an authentication token. You must then include the authentication token in each request in the X-Auth-Token header.

For more details about authentication, see the Cloud Block Storage Developer Guide. Remember to replace the placeholders in the following authentication request example with your information:

• yourUserName —Your common Rackspace Cloud user name, as supplied during registra-tion.

• yourApiKey — Your API key.

This guide uses yourUserName and yourApiKey for authentication. For information about other supported authentication methods, see the Authentication tokens in the Cloud Iden-tity Client Developer Guide.

Use the following global endpoint to access the Cloud Identity service for authentication: •https://identity.api.rackspacecloud.com/v2.0/

In Example 4.1, “cURL authentication request: JSON” [6], you authenticate using https://identity.api.rackspacecloud.com/v2.0/tokens, the URL for the Cloud Identity services. The v2.0 component in the URL indicates that you are using ver-sion 2.0 of the Cloud Identity API.

The cURL request uses the -d option to send the specified data in a POST request to the HTTP server.

Example 4.1. cURL authentication request: JSON

curl -d \ '{ "auth": { "RAX-KSKEY:apiKeyCredentials": { "username": "yourUserName", "apiKey": "yourApiKey"} } }' \ -H 'Content-Type: application/json' \

(12)

An HTTP status code of 200 (OK) in the response indicates that the authentication request completed successfully.

In the authentication response, the authentication token id is returned with an expires attribute that specifies when the token expires. Tokens are valid for a finite duration, typ-ically for 24 hours. Remember to supply your authentication token wherever you see the placeholder yourAuthToken in the examples in this guide.

The authentication response also contains the service catalog, which pro-vides endpoints for Rackspace Cloud services. For example, https://

dfw.blockstorage.api.rackspacecloud.com/v1/1234/) is one of the publi-cURL endpoints for Cloud Block Storage in the service catalog.

Your actual account number is after the final slash (/) in the publicURL field, such as 1234 in the preceding endpoint. You must specify your account number in the Cloud Block Storage API request, wherever you see the placeholder yourAccountID specified in the ex-amples in this guide.

Example 4.2. Authenticate response with partial service catalog showing

cloudBlockStorage: JSON

HTTP/1.1 200 OK

Date: Tue, 06 May 2014 18:33:04 GMT Content-Type: application/json { "access": { "token": { "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "expires": "2014-05-07T07:37:46.317Z", "tenant": { "id": "xxxxxx", "name": "xxxxxx" }, "RAX-AUTH:authenticatedBy": [ "APIKEY" ] }, "serviceCatalog": [ { "name": "cloudBlockStorage", "endpoints": [ { "region": "SYD", "tenantId": "xxxxxx", "publicURL": "https://syd.blockstorage.api.rackspacecloud. com/v1/xxxxxx" }, { "region": "DFW", "tenantId": "xxxxxx", "publicURL": "https://dfw.blockstorage.api.rackspacecloud. com/v1/xxxxxx" }, { "region": "ORD",

(13)

"publicURL": "https://ord.blockstorage.api.rackspacecloud. com/v1/830866" }, { "region": "IAD", "tenantId": "xxxxxx", "publicURL": "https://iad.blockstorage.api.rackspacecloud. com/v1/830866" }, { "region": "HKG", "tenantId": "xxxxxx", "publicURL": "https://hkg.blockstorage.api.rackspacecloud. com/v1/830866" } ], "type": "volume" } ] } }

After authentication, you can use cURL to perform POST, GET, PUT, and DELETE requests for the Cloud Block Storage API.

4.2. Creating a block storage volume

Your first step in Cloud Block Storage is to create a volume. To do this, send a POST re-quest.

The HTTP request must include a header to specify the authentication token.

The cURL request uses the -i option to include the HTTP headers in the output, the -X op-tion to specify the HTTP method to use (instead of using the default GET), and the -d op-tion to send data in the request to the HTTP server.

An HTTP status code of 200 (OK) in the response indicates that the volume was successfully created.

Note

You use the source_volid parameter for volume cloning, which has some limitations. You cannot create more than one clone per volume concurrently. Snapshots and volume cloning use the same locking mechanism, so you cannot run a snapshot and a clone of the same volume concurrently.

(14)

Example 4.3. Create a volume: cURL

curl -i -X POST -d \ '{ "volume":{ "display_name": "vol-001", "size": 100 } }' \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" \ https://dfw.blockstorage.api.rackspacecloud.com/v1/yourAccountID/volumes HTTP/1.1 200 OK X-Compute-Request-Id: req-2af6c97a-2397-4e52-a0d0-4fde64cfb88c Content-Type: application/json Content-Length: 399

Date: Tue, 03 Jun 2014 21:45:46 GMT { "volume": { "status": "available", "display_name": "vol-001", "attachments": [ ], "availability_zone": "nova", "bootable": "false", "created_at": "2014-06-03T21:45:45.000000", "display_description": null, "volume_type": "SATA", "snapshot_id": null, "source_volid": null, "metadata": { "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8" }, "id": "a3df5c35-3218-436e-b706-c85edc3f149d", "size": 100 } }

Note

You use the os-volume_attachments API call (/servers/{server_id}/ os-volume_attachments) to attach the new volume to your Next Genera-tion Cloud Server (with the specified {server_id}). For details, see the Next

Generation Cloud Servers Developer Guide. After the volume is attached, the new volume appears as another device on the Next Generation Cloud Server. The volume can then be partitioned, formatted, and mounted for use on the system.

4.3. Listing existing block storage volumes

To list all of the block storage volumes that you have created in a single region, send a GET request.

(15)

The cURL request uses the -i option to include the HTTP headers in the output and the -X option to specify the HTTP method in the request.

An HTTP status code of 200 (OK) in the response indicates that the request successfully completed.

Example 4.4. List volumes: cURL

curl -i -X GET https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/volumes \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" HTTP/1.1 200 OK X-Compute-Request-Id: req-7941b291-f226-459d-9a78-5d38660f3ae7 Content-Type: application/json Content-Length: 1179

Date: Wed, 04 Jun 2014 16:52:15 GMT { "volumes": [ { "status": "available", "display_name": "vol-001", "attachments": [ ], "availability_zone": "nova", "bootable": "false", "created_at": " 2014-06-03T21:45:45.000000 ", "display_description": null, "volume_type": "SATA", "snapshot_id": null, "source_volid": null, "metadata": { "storage-node": " 3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8 " }, "id": " a3df5c35-3218-436e-b706-c85edc3f149d ", "size": 100 } ] }

4.4. Showing volume details

To show details about a specified volume, send a GET request that includes the volume ID. The HTTP request must include a header to specify the authentication token.

(16)

Example 4.5. Show volume details: cURL

curl -i -X GET https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/volumes/yourVolumeID \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" HTTP/1.1 200 OK X-Compute-Request-Id: req-0ec1d1e0-c591-47d2-a8e7-9a8923e495b2 Content-Type: application/json Content-Length: 554

Date: Wed, 04 Jun 2014 18:15:24 GMT { "volume": { "status": "available", "display_name": "vol-001", "attachments": [ ], "availability_zone": "nova", "bootable": "false", "created_at": "2014-06-03T21:45:45.000000", "os-vol-tenant-attr:tenant_id": "yourAccountID", "display_description": null, "os-vol-host-attr:host": "lunr", "volume_type": "SATA", "snapshot_id": null, "source_volid": null, "os-vol-mig-status-attr:name_id": null, "metadata": { "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8" }, "id": "a3df5c35-3218-436e-b706-c85edc3f149d", "os-vol-mig-status-attr:migstat": null, "size": 100 } }

4.5. Updating a volume

To modify a volume’s name, description, or both, send a PUT request that includes the vol-ume ID.

The cURL request uses the -i option to include the HTTP headers in the output, the -X op-tion to specify the HTTP method to use (instead of using the default ), and the -d option to send data in the request to the HTTP server.

(17)

Example 4.6. Update volume: cURL

curl -i -X PUT -d \ '{ "volume":{ "display_name":"newName", "display_description":"newDescription" } }'\ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" \ https://dfw.blockstorage.api.rackspacecloud.com/v1/yourAccountID/ volumes/yourVolumeID HTTP/1.1 200 OK X-Compute-Request-Id: req-8a131657-46a3-435b-bee4-b612c79c8c09 Content-Type: application/json Content-Length: 411

Date: Wed, 04 Jun 2014 18:29:43 GMT { "volume": { "status": "available", "display_name": "newName", "attachments": [ ], "availability_zone": "nova", "bootable": "false", "created_at": "2014-06-03T21:45:45.000000", "display_description": "newDescription", "volume_type": "SATA", "snapshot_id": null, "source_volid": null, "metadata": { "storage-node": "3d0a6f43-d1d9-4fea-bffa-8cf9fc7bf7e8" }, "id": "a3df5c35-3218-436e-b706-c85edc3f149d", "size": 100 } }

4.6. Deleting a volume

To delete a volume when it is no longer in use and the data that it contains is not needed, send a DELETE request that includes the volume ID.

Note

Deleting a volume deletes all the data within it. You cannot recover the data unless it is backed up before the volume is deleted.

The cURL request uses the -i option to include the HTTP headers in the output and the -X option to specify the HTTP method to use (instead of using the default).

(18)

An HTTP status code of 202 (Accepted) in the response indicates that the delete request has been accepted for processing and the volume will be deleted.

Example 4.7. Delete volume: cURL

curl -i -X DELETE https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/volumes/yourVolumeID \

-H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json"

HTTP/1.1 202 Accepted

Content-Type: text/html; charset=UTF-8 Content-Length: 0

Date: Wed, 04 Jun 2014 19:17:35 GMT

4.7. Creating a snapshot

A snapshot is a point-in-time copy of the data that a volume contains. You must flush all writes to the volume before you create a snapshot. To do so, either unmount any file sys-tems 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 snap-shot.

To create a snapshot of a block storage volume, send a POST request. The HTTP request must include a header to specify the authentication token.

The cURL request uses the -i option to include the HTTP headers in the output, the -X op-tion to specify the HTTP method to use (instead of using the default GET), and the -d op-tion to send data in the request to the HTTP server.

An HTTP status code of 200 (OK) indicates that the request was accepted and "status": "creating" indicates that the snapshot is in progress.

Example 4.8. Create a snapshot: cURL

curl -i -X POST -d \

'{

"snapshot": {

"display_name": "snap-001",

"display_description": "Daily Backup", "volume_id": "yourVolumeID" } }'\ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" \ https://dfw.blockstorage.api.rackspacecloud.com/v1/yourAccountID/snapshots HTTP/1.1 200 OK X-Compute-Request-Id: req-99d94a3a-1086-4c19-99b4-65d05e2e02f1

(19)

Content-Length: 275

Date: Wed, 04 Jun 2014 20:16:19 GMT {

"snapshot": {

"status": "creating", "display_name": "snap-001",

"created_at": "2014-06-04T20:16:17.000000", "display_description": "Daily Backup",

"volume_id": "c849a193-5275-4527-9e5a-69b2a05933aa", "metadata": { }, "id": "a6211a94-937f-4770-8dae-1813cb643213", "size": 100 } }

4.8. Listing snapshots

To list all of the snapshots that you have created in a single region, send a GET request. The HTTP request must include a header to specify the authentication token.

Example 4.9. List snapshots: cURL

curl -i -X GET https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/snapshots \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" HTTP/1.1 200 OK X-Compute-Request-Id: req-1a938da7-cf74-4ac6-a72f-4c927ae23605 Content-Type: application/json Content-Length: 541

Date: Wed, 04 Jun 2014 20:28:01 GMT { "snapshots": [ { "status": "creating", "display_name": "snap-001", "created_at": "2014-06-04T20:16:17.000000", "display_description": "Daily Backup",

"volume_id": "c849a193-5275-4527-9e5a-69b2a05933aa", "metadata": { }, "id": "a6211a94-937f-4770-8dae-1813cb643213", "size": 100

(20)

}, {

"status": "available", "display_name": "snap-002",

"created_at": "2014-06-04T20:13:34.000000", "display_description": "Weekly Backup",

"volume_id": "1a036384-99b2-4fed-ac05-31f964d6925d", "metadata": { }, "id": "ca320eb7-b371-4dbe-b2e9-2543c952f507", "size": 100 } ] }

4.9. Showing snapshot details

To show details about a specified snapshot, send a GET request that includes the snapshot ID.

Note

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

Example 4.10. Show snapshot details: cURL

curl -i -X GET https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/snapshots/yourSnapshotID \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" HTTP/1.1 200 OK X-Compute-Request-Id: req-7314746b-0670-4160-b6a7-388cafbfd082 Content-Type: application/json Content-Length: 383

Date: Wed, 04 Jun 2014 20:47:48 GMT {

"snapshot": {

"status": "available", "display_name": "snap-002",

"created_at": "2014-06-04T20:13:34.000000", "display_description": "Weekly Backup",

(21)

"volume_id": "1a036384-99b2-4fed-ac05-31f964d6925d", "os-extended-snapshot-attributes:project_id": "yourAccountID", "metadata": { }, "id": "ca320eb7-b371-4dbe-b2e9-2543c952f507", "size": 100 } }

4.10. Updating a snapshot

To modify a snapshot’s name, description, or both, send a PUT request that includes the snapshot ID.

The cURL request uses the -i option to include the HTTP headers in the output, the -X op-tion to specify the HTTP method to use (instead of using the default ), and the -d option to send data in the request to the HTTP server.

Example 4.11. Update a snapshot: cURL

curl -i -X PUT -d \ '{ "snapshot":{ "display_name":"newSnapshotName", "display_description":"newSnapshotDescription" } }' \ -H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json" \ https://dfw.blockstorage.api.rackspacecloud.com/v1/yourAccountID/ snapshots/yourSnapshotID HTTP/1.1 200 OK X-Compute-Request-Id: req-8a131657-46a3-435b-bee4-b612c79c8c09 Content-Length: 358

Content-Type: text/html; charset=UTF-8 Date: Wed, 04 Jun 2014 20:59:12 GMT { "snapshot": { "created_at" : "2014-06-04T20:13:34.000000", "status": "available", "display_name": "newSnapshotName", "display_description": "newSnapshotDescription", "id": "a3df5c35-3218-436e-b706-c85edc3f149d", "size": 100, "volume_id" : "1a036384-99b2-4fed-ac05-31f964d6925d" } }

(22)

4.11. Deleting a snapshot

To delete a snapshot, send a DELETE request that includes the snapshot ID. The HTTP request must include a header to specify the authentication token.

The cURL request uses the -i option to include the HTTP headers in the output and the -X option to specify the HTTP method to use (instead of using the default).

An HTTP status code of 202 (Accepted) in the response indicates that the delete request has been accepted for processing and the snapshot will be deleted.

Example 4.12. Delete a snapshot: cURL

curl -i -X DELETE https://dfw.blockstorage.api.rackspacecloud.com/ v1/yourAccountID/snapshots/yourSnapshotID \

-H "X-Auth-Token: yourAuthToken" \ -H "Content-Type: application/json"

HTTP/1.1 202 Accepted

Content-Type: text/html; charset=UTF-8 Content-Length: 0

Date: Wed, 04 Jun 2014 21:09:15 GMT

4.12. Other cURL Commands

You can issue any of the REST methods defined for Cloud Block Storage with the cURL utili-ty.

Note that generally each time cURL is invoked to perform an operation, a separate TCP/IP and SSL connection is created and then discarded. The language APIs, in contrast, are de-signed to reuse connections between operations and therefore provide much better per-formance. We recommend that you use one of the language APIs (for example, Python or Ruby) in your production applications and limit cURL to quick-and-easy testing and trou-bleshooting.

(23)

5. Additional resources

For information about all Cloud Block Storage API operations, see the Cloud Block Storage Developer Guide at docs.rackspace.com. All you need to get started with the Cloud Block Storage API is in this getting started guide and the developer guide. For additional informa-tion about Cloud Block Storage, see the Knowledge Center.

The official support channels (phone, chat, email, forums, and knowledge base arti-cles) for Cloud Block Storage are available through the Rackspace Cloud website at www.rackspace.com.

If the Cloud Block Storage system is not functioning as expected, you can review the System Status page. This page is updated to reflect up-to-date information about the system’s cur-rent health and status.

Interested users can also follow updates and announcements for Rackspace on Twitter. Visit the Product Feedback Forum and tell us what you think about Cloud Block Storage. Developers are also encouraged to join some of the members of the Cloud Block Storage team at external.irc.rackspace.com on the #cbs channel. This is not an official Cloud Block Storage support channel but should rather be viewed as a community meeting place to share ideas and discuss Cloud Block Storage.

This API uses standard HTTP 1.1 response codes as documented at HTTP Status Code Defini-tions.

(24)

6. Document change history

This version of the guide replaces and obsoletes all earlier versions. The most recent changes are described in the following table:

Revision Date Summary of Changes

July 27, 2015 • Added OnMetal Cloud Servers in the Overview because you can now attach an OnMetal server to a Cloud Block Storage volume.

March 4, 2015 • For the Rackspace Cloud Identity service, removed the London endpoint. Rackspace now has one global endpoint for authentication. See Section 4.1, “Generating an authentication to-ken” [6].

January 14, 2015 • Added a link to additional authentication methods, including multi-factor authentication, in

Section 4.1, “Generating an authentication token” [6].

July 22, 2014 • Added a link to guidance on choosing a regionalized endpoint in Chapter 3, “Service access endpoints” [5].

docs.rackspace.com/api

Rackspace Cloud Block Storage Getting Started Guide

Table of Contents

List of Tables

List of Examples

1. Overview

Note

2. Sending requests to the API

2.1. Prerequisites for running examples

2.2. Sending API requests by using cURL

Table 2.1. cURL command-line options

Note

2.3. Copying and pasting cURL request examples

into a terminal window

Note

Example 2.1. cURL authentication request: JSON

Tip

3. Service access endpoints

Table 3.1. Cloud Block Storage regionalized service endpoints

4. Using the API directly by using cURL

4.1. Generating an authentication token

Example 4.1. cURL authentication request: JSON

Example 4.2. Authenticate response with partial service catalog showing

cloudBlockStorage: JSON

4.2. Creating a block storage volume

Note

Example 4.3. Create a volume: cURL

Note

4.3. Listing existing block storage volumes

Example 4.4. List volumes: cURL

4.4. Showing volume details

Example 4.5. Show volume details: cURL

4.5. Updating a volume

Example 4.6. Update volume: cURL

4.6. Deleting a volume

Note

Example 4.7. Delete volume: cURL

4.7. Creating a snapshot

Example 4.8. Create a snapshot: cURL

4.8. Listing snapshots

Example 4.9. List snapshots: cURL

4.9. Showing snapshot details

Note

Example 4.10. Show snapshot details: cURL

4.10. Updating a snapshot

Example 4.11. Update a snapshot: cURL

4.11. Deleting a snapshot

Example 4.12. Delete a snapshot: cURL

4.12. Other cURL Commands

5. Additional resources

6. Document change history