GET'> PUT'> POST'> DELETE'> '> '> ]> Block Storage API Reference OpenStack Foundation 2010-2014 OpenStack Foundation API v1 and extensions OpenStack Block Storage Copyright details are filled in by the template. This document is intended for software developers interested in developing applications using the &PRODNAME; Application Programming Interface (API). 2014-08-05 Removed and replaced WADL references with link to Block Storage API v1 (CURRENT). 2014-06-17 Added common response status codes returned by Block Storage. 2013-02-18 Updated v1 documentation. 2012-12-17 Edits to initial version. 2012-10-17 Initial release. OpenStack Block Storage provides volume management with OpenStack Compute. This document describes the features available with the &API;. We welcome feedback, comments and bug reports at bugs.launchpad.net/Cinder.

This guide is for software developers who develop applications by using the &API;. It assumes the reader has a general understanding of storage and is familiar with: ReSTful web services HTTP/1.1 conventions JSON and/or XML data serialization formats

You can download the most current versions of the API-related documents from docs.openstack.org/api/. This API uses standard HTTP 1.1 response codes as documented at: www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

&PRODNAME; is a block-level storage solution that allows customers to mount drives or volumes to their OpenStack Compute servers. The two primary use cases are (1) to allow customers to scale their storage independently from their compute resources, and (2) to allow customers to utilize high performance storage to serve database or I/O-intensive applications. Interactions with Block Storage occur programmatically via the Block Storage API as described in this Developer Guide. Highlights of &PRODNAME; include: Mount a drive to a Compute server to scale storage without paying for more compute capability. &PRODNAME; is an add-on feature to OpenStack Nova Compute in Folsom versions and earlier. Block Storage is multi-tenant rather than dedicated. Block Storage allows you to create snapshots that you can save, list, and restore.

To use the &PRODNAME; API effectively, you should understand several key concepts:

A volume is a detachable block storage device. You can think of it as a USB hard drive. It can only be attached to one instance at a time.

A snapshot is a point in time copy of the data contained in a volume.

The volume type is the type of a block storage volume. You may define whatever types work best for you, such as SATA, SCSCI, SSD, etc. These can be customized or defined by the OpenStack admin. You may also define extra_specs associated with your volume types. For instance, you could have a VolumeType=SATA, with extra_specs (RPM=10000, RAID-Level=5) . Extra_specs are defined and customized by the admin.

An instance is a virtual machine that runs inside the cloud.

The high-level task flow for Cinder is as follows: The tenant creates a volume. For example, the tenant creates a 30G volume called vol1. $cinder create --display-name vol1 30 This gives the tenant a volume id 521752a6-acf6-4b2d-bc7a-119f9148cd8c. The tenant attaches that volume to a virtual machine (VM) 616fb98f-46ca-475e-917e-2563e5a8cd19: For example A: $ nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb

You can use cURL to try the authentication process in two steps: get a token; send the token to a service. Get an authentication token by providing your username and either your API key or your password. Here are examples of both approaches: You can request a token by providing your username and your password. curl -X POST https://auth.api.openstackcloud.com/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json' Successful authentication returns a token which you can use as evidence that your identity has already been authenticated. To use the token, pass it to other services as an X-Auth-Token header. Authentication also returns a service catalog, listing the endpoints you can use for Cloud services. Use the authentication token to send a GET to a service you would like to use. Authentication tokens are typically valid for 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint. If you are programmatically parsing an authentication response, please be aware that service names are stable for the life of the particular service and can be used as keys. You should also be aware that a user's service catalog can include multiple uniquely-named services which perform similar functions.

The Block Storage API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for calls that have a request body. The response format can be specified in requests either by using the Accept header or by adding an .xml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence. Some operations support an Atom representation that can be used to efficiently determine when the state of services has changed.

Response formats

Format	Accept header	Query extension	Default
JSON	application/json	.json	Yes
XML	application/xml	.xml	No

In the request example below, notice that Content-Type is set to application/json, but application/xml is requested via the Accept header: GET /v1/441446/types HTTP/1.1 Host: dfw.blockstorage.api.openstackcloud.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Accept: application/xml Therefore an XML response format is returned: HTTP/1.1 200 OK Date: Fri, 20 Jul 2012 20:32:13 GMT Content-Length: 187 Content-Type: application/xml X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 <?xml version='1.0' encoding='UTF-8'?> <volume_types> <volume_type id="1" name="SATA"> <extra_specs/> </volume_type> <volume_type id="2" name="SSD"> <extra_specs/> </volume_type> </volume_types>

All accounts, by default, have a preconfigured set of thresholds (or limits) to manage capacity and prevent abuse of the system. The system recognizes two kinds of limits: rate limits and absolute limits. Rate limits are thresholds that are reset after a certain amount of time passes. Absolute limits are fixed.

Rate limits are specified in terms of both a human-readable wild-card URI and a machine-processable regular expression. The regular expression boundary matcher '^' takes effect after the root URI path. For example, the regular expression ^/v1.0/instances would match the bolded portion of the following URI: https://dfw.blockstorage.api.openstackcloud.com/v1.0/instances. The following table specifies the default rate limits for all API operations for all &GET;, &POST;, &PUT;, and &DELETE; calls for volumes:

Default rate limits

Verb	URI		RegEx		Default
&GET; changes-since	*/instances/*		^/v\d+\.\d+/\d+/instances.*		3/minute
&POST;	*/instances/*		^/v\d+\.\d+/\d+/instances.*		10/minute
&POST; instances	*/instances/*		^/v\d+\.\d+/\d+/instances.*		50/day
&PUT;	*/instances/*		^/v\d+\.\d+/\d+/instances.*		10/minute
&DELETE;	*/instances/*		^/v\d+\.\d+/\d+/instances.*		100/minute

Rate limits are applied in order relative to the verb, going from least to most specific. For example, although the threshold for &POST; to /v1.0/* is 10 per minute, one cannot &POST; to /v1.0/* more than 50 times within a single day. If you exceed the thresholds established for your account, a 413 (Rate Control) HTTP response will be returned with a Retry-After header to notify the client when it can attempt to try again.

Refer to the following table for the absolute limits that are set.

Absolute limits

Name	Description	Limit
Block Storage	Maximum amount of block storage (in gigabytes)	1 TB

The Block Storage Service uses an ISO-8601 compliant date format for the display and consumption of date/time values. yyyy-MM-dd'T'HH:mm:ss.SSSZ See the table below for a description of the date/time format codes. May 19th, 2011 at 8:07:08 AM, GMT-5 would have the following format: 2011-05-19T08:07:08-05:00

Date and time format codes

Code	Description
yyyy	Four digit year
MM	Two digit month
dd	Two digit day of month
T	Separator for date/time
HH	Two digit hour of day (00-23)
mm	Two digit minutes of hour
ss	Two digit seconds of the minute
SSS	Three digit milliseconds of the second
Z	RFC-822 timezone

When an error occurs, the Block Storage Service returns a fault object containing an HTTP error response code that denotes the type of error. In the body of the response, the system will return additional information about the fault. The following table lists possible fault types with their associated error codes and descriptions. Fault Type Associated Error Code Description badRequest 400 There was one or more errors in the user request. unauthorized 401 The supplied token is not authorized to access the resources, either it's expired or invalid. forbidden 403 Access to the requested resource was denied. itemNotFound 404 The back-end services did not find anything matching the Request-URI. badMethod 405 The request method is not allowed for this resource. overLimit 413 Either the number of entities in the request is larger than allowed limits, or the user has exceeded allowable request rate limits. See the details element for more specifics. Contact support if you think you need higher request rate limits. badMediaType 415 The requested content type is not supported by this service. unprocessableEntity 422 The requested resource could not be processed on at the moment. instanceFault 500 This is a generic server error and the message contains the reason for the error. This error could wrap several error messages and is a catch all. notImplemented 501 The requested method or resource is not implemented. serviceUnavailable 503 The Block Storage Service is not available. The following two instanceFault examples show errors when the server has erred or cannot perform the requested operation: HTTP/1.1 500 Internal Server Error Content-Type: application/xml Content-Length: 121 Date: Mon, 28 Nov 2011 18:19:37 GMT HTTP/1.1 500 Internal Server Error Content-Length: 120 Content-Type: application/json; charset=UTF-8 Date: Tue, 29 Nov 2011 00:33:48 GMT The error code (code) is returned in the body of the response for convenience. The message element returns a human-readable message that is appropriate for display to the end user. The details element is optional and may contain information that is useful for tracking down an error, such as a stack trace. The details element may or may not be appropriate for display to an end user, depending on the role and experience of the end user. The fault's root element (for example, instanceFault) may change depending on the type of error. The following badRequest examples show errors when the volume size is not valid: HTTP/1.1 400 None Content-Type: application/xml Content-Length: 121 Date: Mon, 28 Nov 2011 18:19:37 GMT HTTP/1.1 400 None Content-Length: 120 Content-Type: application/json; charset=UTF-8 Date: Tue, 29 Nov 2011 00:33:48 GMT The following examples show itemNotFound errors: HTTP/1.1 404 Not Found Content-Length: 147 Content-Type: application/xml; charset=UTF-8 Date: Mon, 28 Nov 2011 19:50:15 GMT HTTP/1.1 404 Not Found Content-Length: 78 Content-Type: application/json; charset=UTF-8 Date: Tue, 29 Nov 2011 00:35:24 GMT

For information about Block Storage API operations, see Block Storage API v1 (CURRENT).