Latest revision as of 12:00, 11 October 2013

A Volume provides storage space that can be used with your Server. This storage space is independent from the storage space that is included with your Server. Once a volume is created, it can be easily attached to a Server. Once attached, it will appear as a mounted device. You can attach multiple volumes to a Server.

[edit] POST /accounts/{accountId}/flexcloud/volumes

This operation will create a new volume.

[edit] Request

[edit] Parameters

accountId - string

The selected account Id.

[edit] JSON

{
    "volume" : {
        "display_name" : "{display_volume_name}",
        "display_description" : "{display_volume_description}",
        "size" : {size_quantity},
        "volume_type" : "{volume_type_id}",
        "metadata" : {
            "contents": "{contents_type}"
        },
        "availability_zone" : "{availability_zone_id}"
   }
}

[edit] volume

display_name - string

Display name for this volume.

display_description - string

Descriptive information for this volume.

size - int

Volume size.

volume_type - string

Identifier of volume type. *(Unused in the current API version - please pass empty value).

metadata - string

Additional metadata info.

availability_zone - string

Identifier of the availability zone into which this volume is created.

[edit] Response

[edit] JSON

{
   "volume": {
       "status": "{volume_status}" 
       "id": "{volume_id}",
       "display_name" : "{display_volume_name}",
       "display_description" : "{display_volume_description}",
       "size" : {size_quantity},
       "volume_type" : "{volume_type_id}",
       "metadata" : {
           "contents": "{contents_type}"
       },
       "availability_zone" : "{availability_zone_id}"
       "snapshot_id": "",
       "attachments": [],
       "created_at": "2012-02-14T20:53:07Z"
   }
}

[edit] volume

status - string

Current status of the volume instance. Possible values: Pending, Open and ClosePending.

id - string

Identifier of the volume instance.

display_name - string

Display name for this volume.

display_description - string

Descriptive information for this volume.

size - int

Volume size.

volume_type - string

Identifier of the volume type used. *(Unused in the current API version - please pass empty value).

metadata - string

Additional metadata info.

availability_zone - string

Identifier of the availability zone into which this volume is created.

snapshot_id - string

Identifier of the snapshot associated with this volume.

attachments - list

List of attachments this volume is associated with.

created_at - string

Volume creation timestamp.

[edit] Response Codes

Success

HTTP/1.1 200 OK

Failure

HTTP/1.1 400 Bad Request

HTTP/1.1 401 Unauthorized : This server could not verify that you are authorized to access the document you requested. Either you supplied the wrong credentials (e.g., bad password), or your browser does not understand how to supply the credentials required.

HTTP/1.1 404 Not Found - The resource does not exist.

HTTP/1.1 409 Conflict

[edit] Examples

Successfully create a new volume

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "volume" : {
        "display_name" : "test_volume_001",
        "display_description" : "Test_Volume_001_Description.",
        "size" : 30,
        "volume_type" : "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata" : {
            "contents": "junk"
        },
        "availability_zone" : "test_zone"
   }
 } 

Response Code:

HTTP/1.1 200 OK

Response Body:

{
    "volume": {
        "status": "Pending",
        "id": 8,
        "display_name" : "test_volume_001",
        "display_description" : "Test_Volume_001_Description.",
        "size" : 30,
        "availability_zone" : "test_zone"
        "attachments": [],
        "created_at": "2012-05-07 15:15:21.678868"
    }
}

Failure while trying to create a new volume with an already existing volume name

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "volume" : {
        "display_name" : <span style="color:red">"test_volume_001"</span>,
        "display_description" : "Test creating a new volume with already existing volume name.",
        "size" : 30,
        "volume_type" : "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata" : {"contents": "junk"},
        "availability_zone" : "test_zone"
   }
 }

Response Code:

HTTP/1.1 409 Conflict

Response Body:

 {
   "conflict": {
      "message": "VolumeNameAlreadyExists", 
      "code": 409, 
      "details": "hbs name already exists",
      "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
   }
 }

Failure while trying to create a new volume with a volume name that is too long

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "volume" : {
        "display_name" : <span style="color:red">"vol-test-name-tooooooooooooooooooooooooooooooooooooooooooolong"</span>,
        "display_description" : "Test creating a volume with too long volume name.",
        "size" : 30,
        "volume_type" : "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata" : {"contents": "junk"},
        "availability_zone" : "test_zone"
   }
 }

Response Code:

HTTP/1.1 400 Bad Request

Response Body:

 {
    "badRequest": {
       "message": "DisplayNameTooLong", 
       "code": 400, 
       "details": "String length exceeded. check your arguments",
       "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
    }
 }

Failure while trying to create a new volume with an invalid availability zone(empty zone)

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "volume" : {
        "display_name" : "vol-test-name-invalid-zone",
        "display_description" : "Test creating a volume with invalid availability zone(empty zone).",
        "size" : 10,
        "volume_type" : "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata" : {"contents": "junk"},
        "availability_zone" : <span style="color:red">""</span>
   }
 }

Response Code:

HTTP/1.1 400 Bad Request

Response Body:

 {
    "badRequest": {
       "message": "Invalid", 
       "code": 400, 
       "details": "",
       "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
    }
 }

Failure while trying to create a new volume with an invalid volume size

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "volume" : {
        "display_name" : "vol-test-name-invalid-zone",
        "display_description" : "Test creating a volume with invalid availability zone(empty zone).",
        "size" : <span style="color:red">500</span>,
        "volume_type" : "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata" : {"contents": "junk"},
        "availability_zone" : "test_zone"
   }
 }

Response Code:

HTTP/1.1 400 Bad Request

Response Body:

 {
    "badRequest": {
       "message": "VolumeSize", 
       "code": 400, 
       "details": "not available HBS Size",
       "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
    }
 }

Unauthorized access

POST http(s)://{api_server}/accounts/{accountId}/flexcloud/volumes

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded fake_authentication_string

Response Code:

HTTP/1.1 401 Unauthorized

Response Body:

    401 Unauthorized
    This server could not verify that you are authorized to
    access the document you requested.  Either you supplied the
    wrong credentials (e.g., bad password), or your browser
    does not understand how to supply the credentials required.

Failure while trying to pass invalid account number

POST http(s)://{api_server}/accounts/fake/flexcloud/volumes

Response Code:

HTTP/1.1 404 Not Found

Response Body:

 {
    "itemNotFound" : {
       "message": "Resource not found", 
       "code": 404, 
       "details": "",
       "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
    }
 }

[edit] Alternative URI /volumes

An alternative way to execute this call is to omit the accountId portion of the URI. In this case the system assumes the request is executed for the account identified in the authorization header.

POST /volumes