Revision as of 09:25, 24 May 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.

POST /volumes

This operation will create a new volume.

Request

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}"
   }
}

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.

Response

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"
   }
}

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.

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 409 Conflict

Examples

Successfully create a new volume

POST http(s)://{api_server}/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}/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 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}/volumes

Request Headers:

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

Request Body:

{
   "volume" : {
       "display_name" : "vol-test-name-tooooooooooooooooooooooooooooooooooooooooooolong",
       "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}/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" : ""
  }
}

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}/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" : 500,
       "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}/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.