Cyclades include the Block Storage Service of Synnefo. The Cyclades/Block Storage API complies with OpenStack Block Storage version 2, with custom extensions when needed.
This document’s goals are:
Users and developers who wish to access Cyclades through its REST API are advised to use the kamaki command-line client and the associated python library, instead of making direct calls.
All requests use the same authentication method: an X-Auth-Token header is passed to the service, which is used to authenticate the user and retrieve user related information. No other user details are passed through HTTP.
Volumes
Description | URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|---|
List | /volumes | GET | ✔ | ✔ |
/volumes/detail | GET | ✔ | ✔ | |
Create | /volumes | POST | ✔ | ✔ |
Get Details | /volumes/<volume id> | GET | ✔ | ✔ |
Update | /volumes/<volume id> | PUT | ✔ | ✔ |
Delete | /volumes/<volume id> | DELETE | ✔ | ✔ |
Reassign | /volumes/<volume id>/action | POST | ✔ | ✘ |
Snapshots
Description | URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|---|
List | /snapshots | GET | ✔ | ✔ |
/snapshots/detail | GET | ✔ | ✔ | |
Create | /snapshots | POST | ✔ | ✔ |
Get Details | /snapshots/<snapshot id> | GET | ✔ | ✔ |
Update | /snapshots/<snapshot id> | PUT | ✔ | ✔ |
Delete | /snapshots/<snapshot id> | DELETE | ✔ | ✔ |
Volume types
Description | URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|---|
List | /volume-types | GET | ✔ | ✔ |
Get Details | /volume-types/<volume-type id> | GET | ✔ | ✔ |
List all volumes owned by the user.
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes | GET | ✔ | ✔ |
/volumes/detail | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
401 (Unauthorized) | Missing or expired user token |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | The service is not currently available |
Response body contents:
volumes: [
{
<volume attribute>: <value>,
...
}, ...
]
The volume attributes are listed here
Example List Volumes: JSON (regular)
GET https://example.org/cyclades/v2/volumes
{
"volumes": [
{
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/42",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/42",
"rel": "bookmark"
}
],
"id": "42",
"display_name": "Volume One",
}, {
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/43",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/43",
"rel": "bookmark"
}
],
"id": "43",
"display_name": "Volume Two",
}
]
}
Example List Volumes: JSON (detail)
GET https://example.org/cyclades/v2/volumes/detail
{
"volumes": [
{
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/42",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/42",
"rel": "bookmark"
}
],
"id": "42",
"display_name": "Volume One",
"status": "AVAILABLE",
"size": 2,
"display_description": "The First Volume",
"created_at": "2014-02-21T19:52:04.949734",
"metadata": {},
"snapshot_id": null,
"source_volid": null,
"image_id": null,
"attachments": [],
"volume_type": 1,
"delete_on_termination": True,
"project": "1234"
}, {
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/43",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/43",
"rel": "bookmark"
}
],
"id": "43",
"display_name": "Volume Two",
"status": "AVAILABLE",
"size": 3,
"display_description": "The Second Volume",
"created_at": "2014-03-21T19:52:04.949734",
"metadata": {"requested_by": "John"},
"snapshot_id": null,
"source_volid": null,
"image_id": null,
"attachments": [],
"volume_type": 2,
"delete_on_termination": False,
"project": "1234"
},
]
}
This operation returns detailed information for a volume
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes/<volume id> | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed volume id |
401 (Unauthorized) | Missing or expired user token |
404 (Not Found) | Volume not found |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
volume: {
<volume attribute>: <value>,
...
}
Volume attributes are explained here
Example Get Volume Response
GET https://example.org/cyclades/v2/volumes/44
{
"volume": {
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/44",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/44",
"rel": "bookmark"
}
],
"id": "44",
"display_name": "Volume Three",
"status": "CREATING",
"size": 10,
"display_description": null,
"created_at": "2014-05-13T19:52:04.949734",
"metadata": {},
"snapshot_id": null,
"source_volid": null,
"image_id": null,
"attachments": [],
"volume_type": 2,
"delete_on_termination": False,
"project": "1234"
}
}
Create a new volume
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes | POST | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Content-Type | Type or request body | required | required |
Content-Length | Length of request body | required | required |
Request body contents:
volume: {
<volume attribute>: <value>,
...
}
Volume Attribute | Value | Cyclades | OS/Block Storage |
---|---|---|---|
size | Volume size in GB | required | required |
server_id | An existing VM to create from | required | ✘ |
availability_zone | Respond in xml | ✘ | ✔ |
source_volid | Existing volume to create from | ✘ | ✔ |
display_description | A description | ✔ | ✔ |
snapshot_id | Existing snapshot to create from | ✔ | ✔ |
display_name | The name | required | ✔ |
imageRef | Image to create from | ✔ | ✔ |
volume_type | The associated volume type | ✔ | ✔ |
bootable | Whether the volume is bootable | ✘ | ✔ |
metadata | Key-Value metadata pairs | ✔ | ✔ |
project | Assigned project for quotas | ✔ | ✘ |
Example Create Volume Request: JSON
POST https://example.org/cyclades/v2/volumes
{
"volume": {
"size": 10,
"display_name": "Volume Three",
"server_id": "117",
"volume_type": 1,
}
}
Response
Return Code | Description |
---|---|
202 (OK) | Request succeeded |
400 (Bad Request) | Malformed request data |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Resource (server_id, imageRef, etc,) not found |
413 (Over Limit) | Exceeded some resource limit |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
volume: {
<volume attribute>: <value>,
...
}
Volume attributes are listed here.
Example Create Volume Response: JSON
{
"volume": {
"links": [
{
"href": "https://example.org/cyclades/v2/volumes/44",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/volumes/44",
"rel": "bookmark"
}
],
"id": "44",
"display_name": "Volume Three",
"status": "CREATING",
"size": 10,
"display_description": null,
"created_at": "2014-05-13T19:52:04.949734",
"metadata": {},
"snapshot_id": null,
"source_volid": null,
"image_id": null,
"attachments": [],
"volume_type": 1,
"delete_on_termination": True,
"project": "1234"
}
}
Response
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes/<volume id> | PUT | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Content-Type | Type or request body | required | required |
Content-Length | Length of request body | required | required |
Request body contents:
volume: {
<volume attribute>: <value>,
...
}
Attribute | Description | Cyclades | OS/Block Storage |
---|---|---|---|
display_name | Server name | ✔ | ✔ |
display_description | Descrition | ✔ | ✔ |
delete_on_termination | Switch this attribute | ✔ | ✘ |
Example Rename Server Request: JSON
POST https://example.org/cyclades/v2/volumes/42
{"volume": {"display_name": "New name"}}
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed request |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Volume not found |
409 (Build In Progress) | Volume is not ready yet |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
volume: {
<volume attribute>: <value>,
...
}
Volume attributes are explained here
Example update volume Response
{
"volume": {
"id": "42",
"display_name": "New Name",
...
}
}
Response
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes/<volume id>/metadata | POST/PUT | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Content-Type | Type or request body | required | required |
Content-Length | Length of request body | required | required |
Request body contents:
volume: {
<key>: <value>,
...
}
Example Append Metadata Request: JSON
POST https://example.org/cyclades/v2/volumes/42/metadata
{"metadata": {"key_to_append": "value_to_append"}}
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed request |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Volume not found |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
metadata: {
<key>: <value>,
...
}
Example update volume Response
{
"metadata": {
"key1": "value1",
"key2": "value2",
...
}
}
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes/<volume id> | DELETE | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
202 (OK) | Request succeeded |
400 (Bad Request) | Malformed server id |
401 (Unauthorized) | Missing or expired user token |
404 (Not Found) | Volume not found |
409 (Build In Progress) | Volume is not ready yet |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | Action not supported or service currently |
unavailable |
Reassign the volume to a (different) project (change quota limits)
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/volumes/<volume id>/action | POST | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Request
Request body contents:
reassign: {project: <project id>}
Example reassign volume Request
POST https://example.org//cyclades/v2/volumes/42/action
{"reassign": {"project": "4321"}}
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed request |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Volume not found |
409 (Build In Progress) | Volume is not ready yet |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
List all snapshots related to the user.
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/snapshots | GET | ✔ | ✔ |
/snapshots/detail | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
401 (Unauthorized) | Missing or expired user token |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | The service is not currently available |
Response body contents:
snapshots: [
{
<snapshot attribute>: <value>,
...
}, ...
]
The snapshot attributes are listed here
Example List Snapshots: JSON (regular)
GET https://example.org/cyclades/v2/snapshots
{
"snapshots": [
{
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "bookmark"
}
],
"id": "42",
"display_name": "Snapshot One",
"status": "AVAILABLE",
"size": 2,
"display_description": null,
"created_at": "2014-05-19T19:52:04.949734",
"metadata": {},
"volume_id": "123",
"os-extended-snapshot-attribute:progress": "100%"
}, {
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/43",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/43",
"rel": "bookmark"
}
],
"id": "43",
"display_name": "Snapshot Two",
"status": "AVAILABLE",
"size": 3,
"display_description": null,
"created_at": "2014-05-20T19:52:04.949734",
"metadata": {},
"volume_id": "124",
"os-extended-snapshot-attribute:progress": "100%"
}
]
}
Example List Snapshots: JSON (detail)
GET https://example.org/cyclades/v2/snapshots/detail
{
"snapshots": [
{
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "bookmark"
}
],
"id": "42",
"display_name": "Snapshot One",
"status": "AVAILABLE",
"size": 2,
"display_description": null,
"created_at": "2014-05-19T19:52:04.949734",
"metadata": {},
"volume_id": "123",
"os-extended-snapshot-attribute:progress": "100%"
}, {
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/43",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/43",
"rel": "bookmark"
}
],
"id": "43",
"display_name": "Snapshot Two",
"status": "AVAILABLE",
"size": 3,
"display_description": null,
"created_at": "2014-05-20T19:52:04.949734",
"metadata": {},
"volume_id": "124",
"os-extended-snapshot-attribute:progress": "100%"
}
]
}
This operation returns detailed information for a snapshot
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/snapshots/<snapshot id> | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed volume id |
401 (Unauthorized) | Missing or expired user token |
404 (Not Found) | Snapshot not found |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
snapshot: {
<snapshot attribute>: <value>,
...
}
Snapshot attributes are explained here
Example Get Snapshot Response
GET https://example.org/cyclades/v2/snapshots/sn4p5h071
{
"snapshot": {
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/42",
"rel": "bookmark"
}
],
"id": "42",
"display_name": "Snapshot One",
"status": "AVAILABLE",
"size": 2,
"display_description": null,
"created_at": "2014-05-19T19:52:04.949734",
"metadata": {},
"volume_id": "123",
"os-extended-snapshot-attribute:progress": "100%",
}
}
Create a new snapshot
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/snapshots | POST | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Content-Type | Type or request body | required | required |
Content-Length | Length of request body | required | required |
Request body contents:
snapshot: {
<snapshot attribute>: <value>,
...
}
Volume Attribute | Value | Cyclades | OS/Block Storage |
---|---|---|---|
volume_id | Volume to create snapshot from | required | required |
display_name | The name | ✔ | ✔ |
display_description | A description | ✔ | ✔ |
force | Whether to snapshot | ✘ | ✔ |
Example Create Volume Request: JSON
POST https://example.org/cyclades/v2/volumes
{
"volume": {
"volume_id": "44",
"display_name": "Snapshot Three"
}
}
Response
Return Code | Description |
---|---|
202 (OK) | Request succeeded |
400 (Bad Request) | Malformed request data |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Snapshot not found |
413 (Over Limit) | Exceeded some resource limit |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
snapshot: {
<snapshot attribute>: <value>,
...
}
Snapshots attributes are listed here.
Example Create Snapshot Response: JSON
{
"snapshot": {
"links": [
{
"href": "https://example.org/cyclades/v2/snapshots/44",
"rel": "self"
}, {
"href": "https://example.org/cyclades/v2/snapshots/44",
"rel": "bookmark"
}
],
"id": "44",
"display_name": "Snapshot Three",
"status": "CREATING",
"size": 10,
"display_description": null,
"created_at": "2014-05-19T19:52:04.949734",
"metadata": {},
"volume_id": "123",
"os-extended-snapshot-attribute:progress": "100%",
}
}
Response
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/snapshots/<snapshot id> | PUT | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Content-Type | Type or request body | required | required |
Content-Length | Length of request body | required | required |
Request body contents:
snapshot: {
<snapshot attribute>: <value>,
...
}
Attribute | Description | Cyclades | OS/Block Storage |
---|---|---|---|
display_name | Server name | ✔ | ✔ |
display_description | Descrition | ✔ | ✔ |
Example Rename Server Request: JSON
POST https://example.org/cyclades/v2/snapshots/44
{"snapshot": {"display_name": "New name"}}
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed request |
401 (Unauthorized) | Missing or expired user token |
403 (Forbidden) | User is not allowed to perform this operation |
404 (Not Found) | Snapshot not found |
409 (Build In Progress) | Snapshot is not ready yet |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
snapshot: {
<snapshot attribute>: <value>,
...
}
Snapshot attributes are explained here
Example update snapshot Response
{
"snapshot": {
"id": "44",
"display_name": "New Name",
...
}
}
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/snapshots/<snapshot id> | DELETE | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
202 (OK) | Request succeeded |
400 (Bad Request) | Malformed server id |
401 (Unauthorized) | Missing or expired user token |
404 (Not Found) | Snapshot not found |
409 (Build In Progress) | Snapshot is not ready yet |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | Action not supported or service currently |
unavailable |
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/types | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
401 (Unauthorized) | Missing or expired user token |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | The service is not currently available |
Response body contents:
volume_types: [
{
<volume type attribute>: <value>,
...
}, ...
]
The volume type attributes are listed here
Example List Volumes: JSON (regular)
GET https://example.org/cyclades/v2/types
{
"volumes": [
{
"id": 1,
"display_name": "Basic type",
"extra_specs": {...}
}, {
"id": 2,
"display_name": "Special type",
"extra_specs": {...}
}
]
}
This operation returns detailed information for a volume type
Request
URI | Method | Cyclades | OS/Block Storage |
---|---|---|---|
/types/<volume type id> | GET | ✔ | ✔ |
Request Header | Value | Cyclades | OS/Block Storage |
---|---|---|---|
X-Auth-Token | User authentication token | required | required |
Response
Return Code | Description |
---|---|
200 (OK) | Request succeeded |
400 (Bad Request) | Malformed volume type id |
401 (Unauthorized) | Missing or expired user token |
404 (Not Found) | Volume type not found |
500 (Internal Server Error) | The request cannot be completed because of an |
internal error | |
503 (Service Unavailable) | No available backends or service currently |
unavailable |
Response body contents:
volume_type: {
<volume type attribute>: <value>,
...
}
Volume attributes are explained here
Example Get Volume Response
GET https://example.org/cyclades/v2/types/1
{
"volume_type": {
"id": 1,
"display_name": "Volume Three",
"extra_specs": {...}
}
}
Volume attribute | Cyclades | OS/Block Storage |
---|---|---|
id | ✔ | ✔ |
display_name | ✔ | ✔ |
links | ✔ | ✔ |
status | ✔ | ✔ |
size | ✔ | ✔ |
display_description | ✔ | ✔ |
created_at | ✔ | ✔ |
metadata | ✔ | ✔ |
snapshot_id | ✔ | ✔ |
source_volid | ✔ | ✔ |
attachments | ✔ | ✔ |
volume_type | ✔ | ✔ |
delete_on_termination | ✔ | ✔ |
image_id | ✔ | ✘ |
project | ✔ | ✘ |
availability_zone | ✘ | ✔ |
bootable | ✘ | ✔ |
Snapshot attribute | Cyclades | OS/Block Storage |
---|---|---|
id | ✔ | ✔ |
display_name | ✔ | ✔ |
links | ✔ | ✔ |
display_description | ✔ | ✔ |
status | ✔ | ✔ |
created_at | ✔ | ✔ |
size | ✔ | ✔ |
volume_id | ✔ | ✔ |
metadata | ✔ | ✔ |
os-extended-snapshot-attribute:progress | ✔ | ✔ |
os-extended-snapshot-attribute:project_id | ✘ | ✔ |
Snapshot attribute | Cyclades | OS/Block Storage |
---|---|---|
id | ✔ | ✔ |
display_name | ✔ | ✔ |
extra_specs | ✔ | ✔ |