Welcome to CloudSigma API documentation!

Release Notes

Sodium Release

Date Released: 2014-05-20

Neon Release

Date Released: 2014-01-29

  • New drive parameter allowing changing the storage type.
  • Most API calls now support standardised filtering.
  • Asnychronous operations now are exposed via a jobs API.
  • Cloning drives and servers can now change the destinations’ names to differentiate between source and destination.
  • Added audit log documentation.

Fluorine Release

Date Released: 2013-12-10

  • Notification preferences functionality allowing multiple recipients. See Notification contacts.
  • Server runtime details now report I/O statistics for the attached drives in the drives/runtime/io object from the response. See Server Runtime and Server Details.
  • Capabilities call now includes the count allowed snapshots in the snapshots object from the response. See Capabilities.
  • API now returns all numbers as integer literals instead of string literals

Date Released: 2013-11-18

  • Global server context is a place to hold server context information, which is common to all user’s servers. See Global context.
  • A call for querying the account current usage Current usage.
  • Clarifications regarding drive resize Resizing (Update or Fail).
  • Section describing allowed names Permitted characters.
  • Fixed documentation of response status codes Servers / VMs, Snapshots, Cloning.
  • More flexible call for subscriptions auto-renew Autorenewing.
  • Login call returns a json object with the user UUID
  • Server firewall updates are applied every 30 seconds, as opposed to previous versions, when they were applied immediately on change.
  • We now support bursting on IP resources. After the IP subscription has expired, all servers that have the IP attached as static will continue to operate until the user runs out of money. All other servers, will block outgoing traffic originating from that IP - i.e. the IP will stop working on servers on which the user configured it manually.
  • Manually configuring an IP, given to the user via DHCP, to another server owned by the same user, is now prohibited.
  • Buying a new IP resource, will make the same available on all of the user’s servers without power-cycling them. The user can manually configure it on his public network interfaces and it will JUST work.

Oxygen Release

Date Released: 2013-10-07

  • Server context can be updated for a running server, by updating server or drive definition. See below.
  • It is possible to update name, meta, and tags on a running server or a drive mounted on a running server. See server edit and drive edit.
  • Added an action to update a drive, which will fail to update if the drive is mounted on a running serve. It is called resize because size is the only drive attribute which cannot be changed on a drive mounted on a running server. See Resizing (Update or Fail).
  • It is possible to create snapshots for a drive, and later clone the snapshot to a full drive. This makes it possible to restore from a point-in-time version of the snapshot. See Snapshots.
  • Added documentation for uploading drive images though simple HTTP POST. See Upload or Download Drive Images.

Nitrogen Release

Date Released: 2013-08-01

Carbon Release

Date Released: 2013-07-08

Date Released: 2013-05-22

  • Firewall functionality. The user can attach firewall policies to NICs. Each policy may have multiple rules for filtering traffic. See My Network -> policies in WebApp or check Firewall Policies section for API documentation.
  • Web VNC. Users can open VNC sessions directly in WebApp. The browser needs to support websockets. To open a Web VNC session go to server properties on a running server, open VNC tunnel, click on the VNC button and choose whether to open the session in the same browser window or in a new browser window/tab.
  • The old hdd resource is renamed to dssd (Distributed SSD). This is reflected in all areas of the API. The subscriptions API still accepts hdd as an alias, but returns dssd. The capabilities API returns dssd.
  • OAuth support for single sign-on in WebApp. Users can authenticate in WebApp with an existing account from Google, Twitter, LinkedIn, or Facebook. See Profile -> settings to connect you CloudSigma account with an existing OAuth provider.
  • Drive images licenses. Servers running with drives from drives library, which contain software that requires a license need a subscriptions in order to be started. Check Subscriptions -> Purchase -> Software licenses in WebApp to list or purchase software licenses. See Subscriptions for API docs on purchasing licenses, and Licenses list for listing purchased licenses.
  • NIC runtime information, when listing running servers, now is also added to the NIC definition, so that it is easier to access NIC runtime info from the NIC object itself rather than the server runtime. The old NIC runtime information in the server runtime is retained for backward compatibility.
  • Drives attached to stopped servers can now be deleted.

Boron Release

Date Released: 2013-03-19

API HTTP response status code changes

  • HTTP status for PUT (update) requests is changed from 202 Accepted to 200 OK.
  • HTTP status for creation of objects is changed from 202 Accepted to 201 Created. This affects Subscription, Servers, Drives, and Tags creation.
  • HTTP status for Subscriptions Calcultaor is changed from 202 Accepted to 200 OK.
  • HTTP status for actions with asynchronous results is changed from 200 to 202. This affects action calls on Servers (start, stop, clone, open_vnc, close_vnc) and Drives (clone).

Berilium Release

Date Released: 2013-01-16

General Notes

Introduction

API endpoint

Given a server running the CloudSigma API it will be available on the following base URL e.g.:

https://{loc}.cloudsigma.com/api/2.0/

Where {loc} is a subdomain for a specific location. In the rest of the documentation the URL’s will be given relative to that base.

Currently the following CloudSigma location endpoints are available:

Location API endpoint
Zurich, Switzerland https://zrh.cloudsigma.com/api/2.0/
Las Vegas, United States https://lvs.cloudsigma.com/api/2.0/

API Versions

The API version is embedded into the URL. The currently active one is ‘2.0’, e.g.

https://lvs.cloudsigma.com/api/2.0/

General URL Format

API URLs have the following general format:

https://{api_endpoint}/api/{api_version}/{resource}/{object_id}/action/?{get_request_parameters}

Here is a list of the possible URL formats relative to the base url (https://{api_endpoint}/api/{api_version}):

/{resource}/
These URLs usually point to a list of resources like /servers/ or /drives/. It may also point to a single resource object such as /profile/.
/{resource}/{object_id}/
These URLs point to a single resource from a list of resources, for example a single server URL can be: /servers/6e5ceaaa-0cf8-417a-bf47-53e56d4fcaaa/
/{resource}/{object_id}/action/?do={action_name}
Some objects have actions. The name of the action is specified in the ‘do=’ GET parameter. For example a server object has a start action which is called on the following URL: /servers/6e5ceaaa-0cf8-417a-bf47-53e56d4fcaaa/action/?do=start

Authentication

The API supports the following authentication methods :

  • HTTP Basic
  • HTTP Digest
  • Cookie based authentication for web/browser based clients.

HTTP Basic Auth

HTTP Basic Authentication is done with the Authorization header. The value of the header is Basic base64_encode({user email}:{password}). For example a user with email user.email@domain.tld with password pass123 results in a value of user.email@domain.tld:pass123, which when encoded in Base64 would result in the following header:

Authorization: Basic dXNlci5lbWFpbEBkb21haW4udGxkOnBhc3MxMjM=

See RFC 2617 for more detailed discussion of HTTP Basic Authentication.

Digest Access Authentication

In order to use digest authentication, clients should make the request without any authentication, which will result in a 401 Unauthorized response. The response will contain a challenge in the WWW-Authenticate header which looks like:

WWW-Authenticate: Digest nonce="1363185031.81:FCF2:443b657bfd1a7340a0841c704d93a579", realm="users", algorithm="MD5", opaque="d7d89a75f4f6e3044626c6c251456e6b401401e7", qop="auth"

Three hashes (we call them HA1 and HA2 and RESPONSE in the example) need to be calculated to generate the response to the challenge and authenticate. The API uses md5 hashing algorithm (algorithm=”MD5”) and “auth” quality of protection (qup=”auth”):

HA1 = MD5({username}:{realm}:{password})
HA2 = MD5({method}:{uri})
RESPONSE = MD5(HA1:{nonce}:{nc}:{cnonce}:{qop}:HA2)

The values for realm, nonce, and qop are given in the challenge header WWW-Authenticate. The client has to provide the username, password, cnonce, and nc. cnonce or client nonce is a random value generated by the client and nc or nonce counter is a hexadecimal counter which should be incremented with each subsequent request.

The client should send an Authorization header which contains all the values from the WWW-Authenticate response header, together with the following values username, uri, cnonce, nc, and response, which contains the calculated RESPONSE hash.

In the example above a user with an email user.email@domain.tld, and with password pass123 may send the following Authorization header in the next request:

Authorization: Digest username="user.email@domain.tld", realm="users", nonce="1363188235.48:54A3:135f43a8227a1ca54c91da95b0111802", uri="/api/2.0/servers/", cnonce="MDI4Nzcx", nc=00000001, qop=auth, response="06238b01fabaeea8d7923c502a037bb5", opaque="5f0604df80b0c2d09330e802ed47ba5288e5440c", algorithm="MD5"

For more information on Digest access authentication see RFC 2617 or the wikipedia article on Digest Access Authentication.

Data Format (Content Types)

The API supports both the JSON and XML data formats. By default JSON is used. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header. The response contains a Content-Type header specifying the data format returned. The following table summarizes the request and response headers concerning data format:

Header name Specified in Request Specified in Response
Content-Type applies to request body applies to response body
Accept applies to response body not applicable

The values which can be used for data format headers are:

Encoding Header value
JSON application/json or */*
XML application/xml

You can also use a URI parameter ?format=json or ?format=xml to specify the content type of the response, when sending a GET request. This is useful for querying the API manually (via web browser) and should not be used when sending requests programmatically. In case both the Content-Type and URI parameter are used, the URI parameter has precedence. In case there are conflicting URI parameters, the last specified parameter takes precedence. In case of both application/json and application/xml are specified in an Accept header, JSON is returned. If the Accept header contains both */* and application/xml or application/json, the */* is ignored and the more specific content type is used.

Content Compression

Response body data may be compressed with gzip compression in order to minimize the amount of data being transferred over the wire. To request response body compression use the Accept-Encoding header on the request. The response will contain a Content-Encoding header specifying the gzip compression algorithm.

Type Header Value
Request Accept-Encoding gzip
Response Content-Encoding gzip

Request Methods

The API uses different HTTP request methods for different types of operations. In order to list the available HTTP request methods on a URL use an OPTIONS method request on it.

Example:

Request:

OPTIONS /2.0/servers/ HTTP/1.1

Response:

HTTP/1.0 200 OK

GET,PUT,DELETE,POST

The following table specifies that meanings of HTTP methods, which can be used by API clients:

GET:Retrieve a resource or a list of resources.
PUT:Update an existing resource. PUT implies an idempotent action (a request, which when repeated with the same arguments will always yield the same result).
POST:Create a resources, or do an action on an object (like do start action on a server). POST is used for non-idempotent request (requests, which may have different results if repeated multiple times, even if the input data is the same).
DELETE:Delete a resource.
OPTIONS:Get a comma separated list of the supported HTTP methods on a URL.

Response Status Codes

The API uses the standard HTTP status code classes, where a code from 200 to 299 signifies success. Request errors have status codes between 400 and 499, and server side errors have codes between 500 and 599. The following status codes are returned by the API:

Success Status Codes:

200:OK. Successful request.
201:Object Created. This request is used for calls which create new objects, such as create drive or create server. The Location response header contains the URI of the newly created object.
202:Accepted. This header is used for long-running or asynchronous operations such as starting a server or cloning a drive. The header also implies that the request the request may not succeed and may be canceled
204:No Content. The request was successful an there is no content in response body. This status is used for successful DELETE requests. Clients should be aware to not parse the body as it is empty and is not a valid JSON or XML document.

API errors usally contain a body which describes the error. Check the Errors section for explanation of the error message format.

Request Error Status Codes:

400:Bad Request. This status means that there is an error in the request. The request error may be data format error (non-valid JSON or XML) or an invalid value.
401:Unauthorized. The provided credentials are incorrect or missing. This response status is normal part of digest authentication in which case, the response will contain WWW-Authenticate header with an authentication challenge.
402:Payment Required. This error means there are not enough funds in the account to complete action. It occurs when trying to buy subscription without having enough funds in the account, or when trying to start a server without having enough funds for burst usage of 5 days.
403:Forbidden. The provided credentials are correct but the user is not permitted to complete the action. This status is used for either “permission” or “operation not allowed” error.
404:Not Found. The requested object does not exist. This error occurs when requesting non-existing resource. The resource may have never been created, or it may be deleted.
405:Method Not Allowed. This error occurs, when using incorrect HTTP method on an URL. For example DELETE requests are not allowed on /profile/ URL, and will return a 405 status.
406:Not Acceptable. This error occurs when the content type requested through the Accept header is not supported by the API. The content types supported by the API are application/json, application/xml, and */*, which defaults to application/json. If the Accept header of the request does not contain any of this content types, a 406 status will be returned.

System Error Status Code

500:Internal Server Error. This status means a system error has occurred. Please contact support if you encounter such an error.
503:Service Unavailable. This status means that the system temporarily cannot fulfil request. This status is returned for concurrent updates, when the client makes multiple concurrent requests which try to update the same values, or when the system is out of capacity.

Rate Limits

The API server needs to impose call-rate limits to protect the infrastructure from being maliciously overloaded.

Verb URI RegEx Limit
POST .* 10000 / min
POST ^/servers/ 10000 / min
PUT .* 10000 / min
GET .* 10000 / min
DELETE .* 1000 / min

Note: these limits may change in future

Permitted characters

The API accepts Unicode characters, with the recommended charset being UTF-8. The only special case is \0, which terminates the string.

Filtering

The API allows filtering of returned resources through GET parameters. Specific filtering options are listed in the schema. The semantics of the filters are as follows:

AND:

Separate GET parameters are ANDed together:

Example:

?name=test&tag__name=test_tag

It will return resources that match: (name = test) AND (has a tag with name = test_tag)

Same filter applied twice is still ANDed:

Example:

?tag__name=test_tag1&tag__name=test_tag2

It will return resources that match: (has a tag with name = test_tag1) AND (has a tag with name = test_tag2)
OR:

Within one GET parameter, values are split by comma and ORed together:

Example:

?name=name1,name2

It will return resources that match (name = name1) OR (name = name2)

Commas can be escaped by a single backslash and they will be not be used to split and backslashes that precede a comma can be escaped in order to keep allow splitting by commas:

Example:

?name=name\,long\\,name2

It will return resources that match (name = name,long\) OR (name = name2)

Note

OR has a higher priority than AND.

Example:

?name=name1,name2&tag__name=test_tag

It will return resources that match ((name = name1) OR (name = name2)) AND (has a tag with name = test_tag)

Errors

Format

When one or more errors occur, they are returned to the client in an object with three fields:

  • error_message: A description of the error that occurred.
  • error_point: The point at which the error occurred. Always present, but can sometimes be null.

Types

The types of errors:

  • validation: An error occurred while validating the submitted data. If the error is related to a particular field, it will set the error_point.
  • notexist: The object you are trying to access does not exist.
  • backend: There was a problem completing the request on the backend. Please contact the support department.
  • permission: You do not have permission to complete the operation. May set the error_point.
  • database: There was a database error.
  • concurrency: There was a concurrency error caused by two simultaneous conflicting operations (i.e. trying to start and delete a server at the same time). The operation should be retried.
  • billing: There was a billing problem.
  • payment: There was a problem processing your payment.

Example

POST /subscriptions/

Example request:

{
    "amount": "1",
    "from_time": "2012-03-28T14:10:15.948157",
    "period": "2 weeks"
}

Example response:

[
    {
        "error_message": "This field is required",
        "error_point": "resource",
        "error_type": "validation"
    }
]

Capabilities

Allowed HTTP methods

Method Description
GET get the capabilities object

Note

See RFC 2616 for more details on HTTP methods semantics

The capabilities API call is used to gather all the basic, sensible limits of the API, to prevent applying static limits inside the client application.

GET /capabilities/
statuscode 200:no error

Example request:

GET /api/2.0/capabilities/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "drives": {
        "dssd": {
            "max_size": 4391067795456,
            "min_size": 536870912
        },
        "zadara": {
            "max_size": 5905580032000,
            "min_size": 1073741824
        }
    },
    "servers": {
        "cpu": {
            "max": 40000,
            "min": 250
        },
        "cpu_per_smp": {
            "max": 2500,
            "min": 1000
        },
        "mem": {
            "max": 68719476736,
            "min": 268435456
        },
        "smp": {
            "max": 24,
            "min": 1
        }
    },
    "snapshots": {
        "current": 0,
        "max": 600
    }
}

Note

Bare in mind, that these capabilities are dynamic - they are based on the cloud usage, location, etc. For example a location might not support lssd, but support magnetic disk option, or vise versa. If a feature is not supported or is disabled, it will disappear from the result of this call. Most of the limits are straight forward and easy to figure out - they match options on servers and drives. There are some exceptions like:

cpu_per_smp:this means that the cpu, divided by the smp value, if smp > 1, should be in the range between 1000 and 2200 MHz. For example a server with 2000MHz cpu and 2 smp has 1000MHz per smp and is within the range, but a server with 8000MHz cpu and 2 smp has a 4000MHz per smp, which is outside of the allowed range.

Clone naming

When cloning drives or whole servers the paramater for the name of the cloned entity could be omitted. In that scenario clone naming strategy based on the profile settings is being invoked.

Clone naming strategies are kept on clone_naming property in the user profile object. Possible values for it:

  • NONE do not append anything to the cloned drive’s name. [default]
  • COUNTER appends a number at the end of the name or increase it in case there is a number already.
  • DATE appends the current date or try to update it in case there is one already.
  • TIMESTAMP appends the current timestamp or try to update it in case there is one already.

If the date/timestamp at the end is already up-to-date the clone naming strategy will fallback to COUNTER without stripping the date/timestamp before.

Example

Let’s say we have a drive named “test_drive_x” and we’re going to clone it. First we want to check out how the counter strategy is working and we’re going to set the clone_naming property to “COUNTER”.

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now we could clone the drive without bothering to make up a new name for it:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/3564c1c2-c498-40d8-b063-aa173e2ec0c5/",
                    "uuid": "3564c1c2-c498-40d8-b063-aa173e2ec0c5"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_x_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/86164dec-fe21-4590-b2d7-a5733c38b24f/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "86164dec-fe21-4590-b2d7-a5733c38b24f"
        }
    ]
}

Done. Our new drive is named “test_drive_x_1”. If you have never changed the clone_naming property it will be set to “COUNTER” by default. Let’s see how the other two strategies are working.

Starting with “DATE”... (responses below here are stripped for better readability)

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "DATE",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now cloning:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "name": "test_drive_x-2014-06-05"
}

Similary with “TIMESTAMP”...

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "TIMESTAMP",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now cloning:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "name": "test_drive_x-2014-06-05 09:45:56"
}

Drives

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /drives/

Gets the list of drives to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request 1 - default list:

GET /api/2.0/drives/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response 1 - default list:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "status": "unmounted",
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "status": "unmounted",
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "status": "unmounted",
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "status": "unmounted",
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "status": "unmounted",
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

Example request 2 - just uuid and status fields:

GET /api/2.0/drives/?fields=uuid,status&limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response 2 - just uuid and status fields:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "status": "unmounted",
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "status": "unmounted",
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "status": "unmounted",
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "status": "unmounted",
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "status": "unmounted",
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

Detailed listing

GET /drives/detail/

Gets the detailed list of drives with additional information to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/drives/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

List single drive

GET /drives/{uuid}/

Gets detailed information for drive identified by drive_uuid.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Creating

POST /drives/

Creates a new drive or multiple drives.

Status Codes:
  • 201 – object created

Example request:

Create a drive

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "media": "disk",
    "name": "test_drive_0",
    "size": 1073741824
}

or create multiple drives

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_drive_0",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_1",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_2",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_3",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_4",
            "size": 1073741824
        }
    ]
}

or you can omit the {‘objects’: ... } and provide only the list:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

[
    {
        "media": "disk",
        "name": "test_drive_0",
        "size": 1073741824
    },
    {
        "media": "disk",
        "name": "test_drive_1",
        "size": 1073741824
    },
    {
        "media": "disk",
        "name": "test_drive_2",
        "size": 1073741824
    },
    {
        "media": "disk",
        "name": "test_drive_3",
        "size": 1073741824
    },
    {
        "media": "disk",
        "name": "test_drive_4",
        "size": 1073741824
    }
]

Example response

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        }
    ]
}

Editing

PUT /drives/{uuid}/

Edits a drive. Note that if the drive is mounted on a running server only the name, meta, tags, and allow_multimount can be changed. If other fields such as size or media are changed for a drive mounted on a running server these changes will be ignored. To make sure that the changes are either fully applied or an error is returned if impossible, use the resize action (Resizing (Update or Fail)). Note that changing drive size might be a slow operation, and the drive cannot be used during the resizing.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/drives/86468a1e-d622-4080-bb6d-8ec7b635db48/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "media": "cdrom",
    "name": "test_drive_y",
    "size": 1073741824
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "cdrom",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_y",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/86468a1e-d622-4080-bb6d-8ec7b635db48/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "86468a1e-d622-4080-bb6d-8ec7b635db48"
}

Resizing (Update or Fail)

POST /drives/{uuid}/action/?do=resize

In order to make sure that drive changes take effect, one can use the resize action. It updates a drive definition, and returns an error if not possible to completely apply the new drive definition, which may happen if the drive is mounted on a running server. The name of the action is resize because only drive size cannot be changed for a drive mounted on a running server.

Note that the resize action is a full definition update (it can update even name and metadata), so a full definition should be provided to this call.

Example:

POST /api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/action/?do=resize HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/",
    "runtime": {
        "is_snapshotable": null,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 4294967296,
    "snapshots": [],
    "status": "creating",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "df170528-c34d-4009-a806-c7d85c78cad8"
}

Note that the drive in the response is with status resizing:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 2147483648,
            "snapshots": [],
            "status": "resizing",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "df170528-c34d-4009-a806-c7d85c78cad8"
        }
    ]
}

Meta

It is possible to add arbitrary key-value data to a drive definition. See Objects’ metadata field for more information.

Deleting

Single drive

DELETE /drives/{uuid}/

Deletes a single mounted or unmounted drive.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Multiple drives

DELETE /drives/

Deletes multiple mounted or unmounted drives specified by their UUID’s.

statuscode 204:No content, object deletion started.

Example request:

Request body

{"objects":
  [
    {
     "uuid":"b137e217-42b6-4ecf-8575-d72efc2d3dbd",
    },
    {
     "uuid":"e035a488-8587-4a15-ab25-9b7343236bc9",
    },
    {
     "uuid":"feded33c-106f-49fa-a1c4-be5c718ad1b5",
    }
  ]
}

Example response:

HTTP/1.0 204 NO CONTENT

Cloning

POST /drives/{uuid}/action/?do=clone

Clones a drive. Request body is optional and any or all of the key/value pairs can be omitted.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/drives/963e3f37-572a-4e40-b70f-06f093ea7eb5/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "name": "test_drive_y",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/",
                    "uuid": "6c809fa7-f797-4d0f-bbfb-b1b9ba737dda"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_y",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/842e4c44-75a2-4d81-b812-9bc63d3be11e/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "842e4c44-75a2-4d81-b812-9bc63d3be11e"
        }
    ]
}

Note

The name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information

Request schema

{
   "description":"Clone drive",
   "properties":{
          "name":{
                  "description": "Name of the cloned drive",
          }
          "media":{
                  "description": "Media of the cloned drive",
          }
          "affinities":{
                  "description": "Affinities of the cloned drive",
          }
   }
}

Availability Groups

It is possible to query which drives share common storage hosts. See Drives availability groups.

Creating or Cloning Drives to Different Infrastructure (avoid)

It is possible to hint the system which drives are preferred to be on separate physical storage host. See Creating Drives in a Different Availability Group (Create/Clone Avoid).

Licenses

Drives can have licenses attached to them. This means usage of the given drive on a running server requires either posession of subscriptions for the given licenses or additional payment. Typical such example are some drives in the drives library, see Licensed drive images and Licenses list

Storage Types

Every drive has a storage_type on which they live and cannot be changed after creation. New drives by default go to dssd, and clones go to the same medium as their origin, but this can be overriden by passing a storage_type parameter. Allowed storage types can be different per location, so you should refer to the drives section of the capabilities call response, where each storage type is specified alongside with the minimum and maximum size of a single drive.

New in version Neon.

Creating

Example request:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_zadara_drive",
            "size": 1073741824,
            "storage_type": "zadara"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/1c17d5ad-d345-4af1-9fc8-89dec02f0daf/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "1c17d5ad-d345-4af1-9fc8-89dec02f0daf"
        }
    ]
}

Cloning to the same storage type

Example request:

POST /api/2.0/drives/1c17d5ad-d345-4af1-9fc8-89dec02f0daf/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/900f6128-7a0f-49c3-9394-aa4f261c1b25/",
                    "uuid": "900f6128-7a0f-49c3-9394-aa4f261c1b25"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/203cbccd-0736-42dc-b75a-2bdb4db46909/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "203cbccd-0736-42dc-b75a-2bdb4db46909"
        }
    ]
}

Cloning to another storage type

Example request:

POST /api/2.0/drives/3be001aa-16df-453a-a2ab-d13981d56589/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "storage_type": "zadara"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/c360f719-f750-4dfe-bb23-99680179b3e0/",
                    "uuid": "c360f719-f750-4dfe-bb23-99680179b3e0"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive_for_clone",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/50b5cfdf-b286-43e9-8815-dd2c9354644b/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "50b5cfdf-b286-43e9-8815-dd2c9354644b"
        }
    ]
}

Drive State Diagram

_images/DrivesStates.png

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "affinities": {
            "choices": [
                "ssd"
            ],
            "default": [],
            "help_text": "A list of affinities this drive should belong to",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "allow_multimount": {
            "default": false,
            "help_text": "Allow the drive to be mounted on multiple guests. Not taken into account when drive is cdrom.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "licenses": {
            "default": [],
            "fields": {
                "amount": {
                    "default": 1,
                    "help_text": "Number of licenses",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "license": {
                    "default": "No default provided.",
                    "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "user": {
                    "default": null,
                    "help_text": "Owner of the license",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "A list of licenses attached to this drive",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "media": {
            "choices": [
                "cdrom",
                "disk"
            ],
            "default": null,
            "help_text": "Media representation type",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "mounted_on": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the drive",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "runtime": {
            "default": "No default provided.",
            "fields": {
                "is_snapshotable": {
                    "default": "No default provided.",
                    "help_text": "Specifies if the drive supports snapshotting",
                    "readonly": true,
                    "required": true,
                    "type": "boolean"
                },
                "snapshots_allocated_size": {
                    "default": "No default provided.",
                    "help_text": "Sum of the allocated size of this drive's snapshots",
                    "readonly": true,
                    "required": false,
                    "type": "integer"
                },
                "storage_type": {
                    "default": "No default provided.",
                    "help_text": "Underlying storage",
                    "readonly": true,
                    "required": true,
                    "type": "string"
                }
            },
            "help_text": "Runtime information of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "size": {
            "default": null,
            "help_text": "Size of the drive in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "snapshots": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the drive.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "storage_type": {
            "default": "No default provided.",
            "help_text": "Underlying storage",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the drive",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Snapshots

Snapshots are point-in-time versions of a drive. They can be cloned to a full drive, which makes it possible to restore an older version of a VM image.

Snapshots are billed based on their occupied size. Since only the difference from the current drive image is stored, a single snapshot’s size will be equal to the size of the data which was changed since the snapshot was taken. If no data was changed, the snapshot’s size will be zero.

Note that snapshots are billed as drive, so drive subscriptions should be bought in order not to burst on snapshots usage.

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /snapshots/

Gets the list of snapshot to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request - default list:

GET /api/2.0/snapshots/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response - default list:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 6
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_30",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/78db3f50-945d-4795-814b-cff122f6b11f/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:30.563748+00:00",
            "uuid": "78db3f50-945d-4795-814b-cff122f6b11f"
        },
        {
            "allocated_size": null,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_32",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1/",
            "status": "creating",
            "tags": [],
            "timestamp": "2014-06-05 09:53:32.186344+00:00",
            "uuid": "44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_29",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/33c0b447-d545-457f-a01c-156f674095c8/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:29.770356+00:00",
            "uuid": "33c0b447-d545-457f-a01c-156f674095c8"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:31.377681+00:00",
            "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

Detailed listing

GET /snapshots/detail/

Gets the detailed list of snapshots with additional information to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/snapshots/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 6
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_30",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/78db3f50-945d-4795-814b-cff122f6b11f/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:30.563748+00:00",
            "uuid": "78db3f50-945d-4795-814b-cff122f6b11f"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_32",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:32.186344+00:00",
            "uuid": "44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_29",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/33c0b447-d545-457f-a01c-156f674095c8/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:29.770356+00:00",
            "uuid": "33c0b447-d545-457f-a01c-156f674095c8"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:31.377681+00:00",
            "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

List single snapshot

GET /snapshots/{uuid}/

Gets detailed information for snapshot identified by snapshot_uuid.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allocated_size": null,
    "drive": {
        "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
        "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
    },
    "grantees": [],
    "meta": {},
    "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
    "status": "creating",
    "tags": [],
    "timestamp": "2014-06-05 09:53:31.377681+00:00",
    "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
}

Creating

POST /snapshots/

Creates a new snapshot or multiple snapshots.

Status Codes:
  • 201 – object created

Example request:

Create a snapshot

POST /api/2.0/snapshots/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "drive": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84",
    "meta": {
        "key": "val"
    },
    "name": "first_snapshot"
}

Example response

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "allocated_size": null,
            "drive": {
                "resource_uri": "/api/2.0/drives/450357dc-cbe1-471d-b4cc-dbdfe5f28d84/",
                "uuid": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84"
            },
            "grantees": [],
            "meta": {
                "key": "val"
            },
            "name": "first_snapshot",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/",
            "status": "creating",
            "tags": [],
            "timestamp": "2014-06-05 09:52:53.896622+00:00",
            "uuid": "855ebdc8-ce4b-48d0-9d8d-306c9074be29"
        }
    ]
}

Editing

PUT /snapshots/{uuid}/

Edits a snapshot.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "drive": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84",
    "meta": {
        "key": "val_changed",
        "new_key": "new_key_value"
    },
    "name": "first_snapshot_renamed"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allocated_size": 0,
    "drive": {
        "resource_uri": "/api/2.0/drives/450357dc-cbe1-471d-b4cc-dbdfe5f28d84/",
        "uuid": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84"
    },
    "grantees": [],
    "meta": {
        "key": "val_changed",
        "new_key": "new_key_value"
    },
    "name": "first_snapshot_renamed",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/",
    "status": "available",
    "tags": [],
    "timestamp": "2014-06-05 09:52:53.896622+00:00",
    "uuid": "855ebdc8-ce4b-48d0-9d8d-306c9074be29"
}

Metadata

It is possible to add arbitrary key-value data to a snapshot definition. See Objects’ metadata field for more information.

Deleting

Single snapshot

DELETE /snapshots/{uuid}/

Deletes a single snapshot.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Multiple snapshots

DELETE /snapshots/

Deletes multiple mounted or unmounted snapshots specified by their UUID’s.

statuscode 204:No content, object deletion started.

Example request:

Request body

{"objects":
  [
    {
     "uuid":"b137e217-42b6-4ecf-8575-d72efc2d3dbd",
    },
    {
     "uuid":"e035a488-8587-4a15-ab25-9b7343236bc9",
    },
    {
     "uuid":"feded33c-106f-49fa-a1c4-be5c718ad1b5",
    }
  ]
}

Example response:

HTTP/1.0 204 NO CONTENT

Cloning

POST /snapshots/{uuid}/action/?do=clone

Clones a snapshot to a drive. Request body is optional and any or all of the key/value pairs can be omitted.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/snapshots/c6368b7c-9d3d-4631-b008-83b73c05f1bd/action/?do=clone&avoid=d7da5038-ac2d-4776-9097-f60167d6e587 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response: The response is actually a drive definition

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "d7da5038-ac2d-4776-9097-f60167d6e587__2014-06-05__09_52_13",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": {
        "resource_uri": "/api/2.0/drives/fadfc92d-1bfa-4eb2-bddd-491c54df2fae/",
        "uuid": "fadfc92d-1bfa-4eb2-bddd-491c54df2fae"
    },
    "runtime": {
        "is_snapshotable": null,
        "snapshots_allocated_size": 0,
        "storage_type": null
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "cloning_dst",
    "storage_type": null,
    "tags": [],
    "uuid": "fadfc92d-1bfa-4eb2-bddd-491c54df2fae"
}

Note

The name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information

Listing drive snapshots

There are 2 ways of getting all snapshots of a drive

By filtering snapshots

You can apply drive filter to snapshots

GET /snapshots/{uuid}/?drive={drive_uuid}
GET /api/2.0/snapshots/detail/?limit=0&drive=b7cb6615-b6a5-4c31-b755-b86980c64d59 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

In drive definition

In the detailed drive definition there is “snapshots” field

GET /drives/{drive_uuid}/
GET /api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "snapshots": [
        {
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

Request schema

{
   "description":"Clone snapshot",
   "properties":{
          "name":{
                  "description": "Name of the cloned snapshot",
          }
          "media":{
                  "description": "Media of the cloned snapshot",
          }
          "affinities":{
                  "description": "Affinities of the cloned snapshot",
          }
   }
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "allocated_size": {
            "default": "No default provided.",
            "help_text": "Physical size of the snapshot",
            "readonly": true,
            "required": true,
            "type": "integer"
        },
        "drive": {
            "default": null,
            "help_text": "Drive UUID",
            "readonly": false,
            "required": true,
            "type": "related"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Optional human readable name of the snapshot",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the snapshot",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the snapshot.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "timestamp": {
            "default": null,
            "help_text": "Timestamp of the snapshot creation",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the snapshot",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Library Drives

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /libdrives/

Gets the list of library drives to which the authenticated user has access.

param fields:A set of field names specifying the returned fields
statuscode 200:no error

Example request:

GET /api/2.0/libdrives/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 158
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "webserver",
                "general",
                "dbserver"
            ],
            "description": "Ubuntu 12.04.4 Server - 64bit Pre-Installed English with VirtIO support, SSH and Python. Last update on 2014/06/4.",
            "distribution": "Ubuntu",
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n Username: cloudsigma \\n Password: cs2014!!! \\n \\n Detailed Installation Instructions: \\n 1. Clone the Image. \\n The image needs to be cloned and then attached to a server. \\n \\n 2. Connect to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 3. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by ubuntu.com: 1GB RAM and 1GHz CPU \\n \\n 4. Update your administrator password. \\n For security reasons the \"root\" login is disabled (including for ssh) \\n User \"cloudsigma\" is available for access instead. \\n Please be aware that on first login you will be asked to change the initial password. \\n To switch to \"root\" please use the command \"sudo su\" for example. \\n \\n 5. Setup your OS. \\n The timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in. \\n \\n 6. Configuring your Networking. \\n a) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings. \\n b) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n",
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Ubuntu 12.04.4 Server",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/d446038b-784d-4ae4-9a4d-46c7b51b403d/",
            "size": 10737418240,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "d446038b-784d-4ae4-9a4d-46c7b51b403d",
            "version": "12.04.4"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "webserver",
                "general",
                "dbserver"
            ],
            "description": "Ubuntu 12.04.4 - 64bit Pre-Installed English with VirtIO support and SSH. Last update on 2014/06/4",
            "distribution": "Ubuntu",
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n Username: cloudsigma \\n Password: cs2014!!! \\n \\n Detailed Installation Instructions: \\n 1. Clone the Image. \\n The image needs to be cloned and then attached to a server. \\n \\n 2. Connect to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 3. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by ubuntu.com: 1GB RAM and 1GHz CPU \\n \\n 4. Update your administrator password. \\n For security reasons the \"root\" login is disabled (including for ssh) \\n User \"cloudsigma\" is available for access instead. \\n Please be aware that on first login you will be asked to change the initial password. \\n To switch to \"root\" please use the command \"sudo su\" for example. \\n \\n 5. Setup your OS. \\n The timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in. \\n \\n 6. Configuring your Networking. \\n a) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings. \\n b) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n",
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Ubuntu 12.04.4 Desktop",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/0a06a5f5-a74e-4f1d-844e-b00d915cfd3c/",
            "size": 10737418240,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "0a06a5f5-a74e-4f1d-844e-b00d915cfd3c",
            "version": "12.04.4"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "other"
            ],
            "description": "VirtIO Drivers for Windows v.0.1-65",
            "distribution": null,
            "favourite": false,
            "image_type": "install",
            "install_notes": "1. Attach the CD. \\n Please be aware that the CD needs to be attached to the server to IDE.\\n \\n 2. Attach VirtIO devices.\\n \\n The CD image with the VirtIO drivers does not include setup application. You will need to attach additional disk (or CD ) and network interface (recommended private) \\n In order to force windows to detect the new hardware (VirtIO) and require drivers.\\n \\n 3. Drivers installation.\\n \\n You must be logged on as an administrator to perform these steps.\\n \\n Open Device Manager by clicking the Start button Picture of the Start button, clicking Control Panel, clicking System and Maintenance, and then clicking Device Manager.\u200c\\n Administrator permission required If you are prompted for an administrator password or confirmation, type the password or provide confirmation.\\n \\n In Device Manager, locate the device you want to install, and then double-click the device name.\\n \\n Click the Driver tab, and then click install Driver and follow the instructions.\\n \\n Basically you need to browse to the CD subfolders and make sure selecting drivers are compatible with your windows distribution i.e. Win7 for Windows 2008 R2 and Vista for Windows 2008 R1\\n \\n 4. Power cycle and reattach all existing non-VirtIO devices on VirtIO\\n \\n Once you have properly installed drives you can shutdown the server and re-attach the system disk and the network interface on VirtIO. You can also detach all unnecessary devices and power on the server.\\n \\n Please be aware, if you are trying to run windows with system disk attached on VirtIO without installed drivers for VirtIO. Windows will stuck at blue screen error and probably reboot.\\n",
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "VirtIO Drivers for Windows 0.1-65",
            "os": "windows",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/6626f7cd-6085-42a2-a0b4-42262c9c6036/",
            "size": 1000013824,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "6626f7cd-6085-42a2-a0b4-42262c9c6036",
            "version": null
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "general"
            ],
            "description": "Oracle Solaris 11.1 Server - 64bit - Install CD",
            "distribution": null,
            "favourite": false,
            "image_type": "install",
            "install_notes": "1. Attach the CD. \\n Please be aware that the CD needs to be attached to the server as IDE. \\n \\n 2. Attach a Drive. \\n Please be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n \\n 3. Connecting to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 4. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by oracle.com are: 0.5GB RAM and 0.5GHz CPU \\n \\n",
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "Oracle Solaris 11.1 Server",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/07f3cc68-203e-4094-92c6-5d684ad609b1/",
            "size": 613695488,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "http://www.oracle.com/",
            "uuid": "07f3cc68-203e-4094-92c6-5d684ad609b1",
            "version": null
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "dbserver"
            ],
            "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
            "distribution": null,
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
            "jobs": [],
            "licenses": [
                {
                    "amount": 1,
                    "license": {
                        "burstable": true,
                        "long_name": "Windows Server",
                        "name": "msft_p73_04837_core",
                        "resource_uri": "/api/2.0/licenses/12/",
                        "type": "instance",
                        "user_metric": "smp"
                    },
                    "user": null
                },
                {
                    "amount": 1,
                    "license": {
                        "burstable": false,
                        "long_name": "SQL Server Standard Edition",
                        "name": "msft_7nq_00302",
                        "resource_uri": "/api/2.0/licenses/14/",
                        "type": "instance",
                        "user_metric": "smp"
                    },
                    "user": null
                }
            ],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
            "os": "windows",
            "owner": null,
            "paid": true,
            "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
            "size": 64424509440,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "http://www.microsoft.com/",
            "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
            "version": null
        }
    ]
}

Detailed listing

Note

For consistency, we left /libdrives/detail/ url enabled, but it returns the same level of detail as the list call.

List single drive

GET /libdrives/{uuid}/

Gets detailed information for library drive identified by uuid.

statuscode 200:no error

Example request:

GET /api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "arch": "64",
    "category": [
        "dbserver"
    ],
    "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
    "distribution": null,
    "favourite": false,
    "image_type": "preinst",
    "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "os": "windows",
    "owner": null,
    "paid": true,
    "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "size": 64424509440,
    "status": "unmounted",
    "storage_type": null,
    "tags": [],
    "url": "http://www.microsoft.com/",
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
    "version": null
}

Attaching library drive

If the library drive is a CDROM media, you can attach it directly to an owned server the same way you attach a regular drive - specifying the library drive uuid.

Cloning library drive

POST /libdrives/{uuid}/action/?do=clone

If a library drive is not a CDROM, you have to clone it in your account in order to use it. You can clone a library drive the same way you clone a regular drive.

Licensed drive images

Some drives in the library may require additional subscriptions or payment to be used. This is visible from the licenses field in the drive definition. When you clone such image from drives library to your account, the licenses remain bound to the cloned drive and can’t be altered upon drive edit. See also Licenses list regarding how to list all defined licenses.

Recognizing library drives

Note that library drives can be queried through regular drives API using /drives/{uuid}/. If the drive uuid happens to be the uuid of a library drive, the drive defintion will be retrieved. In order to differentiate between owned and library drive, one can check the owner attribute, which is null for library drives.

It is possible to get a library drive through the drives API, because there isn’t a way to know in advance whether an attached drive in a server definition is owned by the user or one from library.

Library drives are not listed in the list and detailed list for ordinary drives.

Example:

Get the drive from /drives/{uuid}/:

GET /api/2.0/drives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "owner": null,
    "permissions": [],
    "resource_uri": "/api/2.0/drives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 64424509440,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433"
}

Notice that there is no owner (it is null).

Get the same drive from /libdrives/{uuid}/:

GET /api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "arch": "64",
    "category": [
        "dbserver"
    ],
    "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
    "distribution": null,
    "favourite": false,
    "image_type": "preinst",
    "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "os": "windows",
    "owner": null,
    "paid": true,
    "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "size": 64424509440,
    "status": "unmounted",
    "storage_type": null,
    "tags": [],
    "url": "http://www.microsoft.com/",
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
    "version": null
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "affinities": {
            "choices": [
                "ssd"
            ],
            "default": [],
            "help_text": "A list of affinities this drive should belong to",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "allow_multimount": {
            "default": false,
            "help_text": "Allow the drive to be mounted on multiple guests. Not taken into account when drive is cdrom.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "arch": {
            "default": null,
            "help_text": "Operating system bit architecture the drive.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "category": {
            "default": [],
            "help_text": "Category of the drive.",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "description": {
            "default": null,
            "help_text": "Description of drive image.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "distribution": {
            "default": null,
            "help_text": "OS distribution of the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "favourite": {
            "default": null,
            "help_text": "Favourite drive image for user.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "image_type": {
            "default": null,
            "help_text": "Type of drive image.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "install_notes": {
            "default": null,
            "help_text": "Install notes for the drive image.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "licenses": {
            "default": [],
            "fields": {
                "amount": {
                    "default": 1,
                    "help_text": "Number of licenses",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "license": {
                    "default": "No default provided.",
                    "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "user": {
                    "default": null,
                    "help_text": "Owner of the license",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "A list of licenses attached to this drive",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "media": {
            "choices": [
                "cdrom",
                "disk"
            ],
            "default": null,
            "help_text": "Media representation type",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "mounted_on": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the drive",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "os": {
            "default": null,
            "help_text": "Operating system of the drive.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "paid": {
            "default": null,
            "help_text": "Paid or free.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "size": {
            "default": null,
            "help_text": "Size of the drive in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the drive.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "storage_type": {
            "default": "No default provided.",
            "help_text": "Underlying storage",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "url": {
            "default": null,
            "help_text": "Operating system bit architecture the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the drive",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "version": {
            "default": null,
            "help_text": "OS version of the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        }
    },
    "filtering": {
        "arch": "exact",
        "category": "exact",
        "distribution": "exact",
        "image_type": "exact",
        "name": "exact",
        "name__icontains": "exact",
        "os": "exact",
        "uuid": "exact",
        "version": "exact"
    }
}

Upload or Download Drive Images

Uploading a drive image

POST https://direct.{loc}.cloudsigma.com/api/2.0/drives/upload/

A drive image can be uploaded by issuing a POST request with the image to /drive/upload/. Note that there is a different domain endpoint for uploads direct.{loc}.cloudsigma.com.

Currently only raw disk images are supported. The request body should contain the raw byte stream of disk a image and should specify correct content type (Content-Type: application/octet-stream) in the request headers. The drive upload API supports only Basic HTTP authentication.

It is very important that the Content-Length contains the correct size of the data to be sent, because it determines the size of the drive which will be created. Note that if the uploaded image is smaller than the minimum drive size (Check Capabilities), it will be resized automatically on upload completion.

It is possible to specify the file name in the path, i.e. to upload the image to /drive/upload/file_name path, but the file name is ignored. This makes it easier to use tools, such as curl, which usually upload to a path ending with the name of the file.

The returned response contains the UUID of the created drive.

Below is an example on how to upload a drive image using curl:

curl --request POST --user email@example.com:password \
     --header 'Content-Type: application/octet-stream' \
     --upload-file /path/to/file \
     https://direct.zrh.cloudsigma.com/api/2.0/drives/upload/

Note that in the above command specifying the Content-Type header also sets curl to not encode the body of the request and leave it as an octet-stream.

The command prints the UUID of the uploaded image. You may want to save it to a file with an output redirect by appending > uploaded_drive_uuid at the end of the command.

By default curl does not show upload progress. You may add –verbose (-v) option if you use curl on the command line to print the progress and speed of upload.

Downloading a drive image

GET https://direct.{loc}.cloudsigma.com/api/2.0/drives/{uuid}/download/

To download a drive image issue a GET request to /drives/{uuid}/download/. Note that there is a different domain endpoint for image download direct.{loc}.cloudsigma.com. The download client should handle HTTP redirects correctly. The resulting response contains an Content-Type: application/octet-stream file. The file name is set to the image UUID in the Content-Disposition header.

Below is an example on how to download a drive image using curl:

curl --location \
     --remote-name --remote-header-name \
     --user email@example.com:password \
     https://direct.zrh.cloudsigma.com/api/2.0/drives/ad64ded1-be81-454a-aa14-d7809cca93eb/download/

The –location option instructs curl to follow redirects. The client is expected to follow HTTP redirects.

The above command uses –remote-header-name to save the image into a file named as specified in Content-Disposition. The name in the content disposition is set to the drive UUID. It is possible to specify a different output name/path with the –output (-o) option. Note that –remote-header-name should always be used together with –remote-name.

Servers / VMs

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /servers/

Gets the list of servers to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/servers/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "name": "test_server_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/3ca429cc-b4f4-42a8-aaa8-3a6df700af06/",
            "runtime": null,
            "status": "stopped",
            "uuid": "3ca429cc-b4f4-42a8-aaa8-3a6df700af06"
        },
        {
            "name": "test_server_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/f50b672f-a963-4b8a-bf05-809b3ffd9a9f/",
            "runtime": null,
            "status": "stopped",
            "uuid": "f50b672f-a963-4b8a-bf05-809b3ffd9a9f"
        },
        {
            "name": "test_server_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888/",
            "runtime": null,
            "status": "stopped",
            "uuid": "5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888"
        },
        {
            "name": "test_server_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/8d483469-faeb-4408-899b-a10df6bf3587/",
            "runtime": null,
            "status": "stopped",
            "uuid": "8d483469-faeb-4408-899b-a10df6bf3587"
        },
        {
            "name": "test_server_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/514a790d-9798-4476-93e9-5cecb4b1c6a3/",
            "runtime": null,
            "status": "stopped",
            "uuid": "514a790d-9798-4476-93e9-5cecb4b1c6a3"
        }
    ]
}

Detailed listing

GET /servers/detail/

Gets the detailed list of servers to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/servers/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_3",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/3ca429cc-b4f4-42a8-aaa8-3a6df700af06/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "3ca429cc-b4f4-42a8-aaa8-3a6df700af06",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_0",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/f50b672f-a963-4b8a-bf05-809b3ffd9a9f/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "f50b672f-a963-4b8a-bf05-809b3ffd9a9f",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_1",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_4",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/8d483469-faeb-4408-899b-a10df6bf3587/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "8d483469-faeb-4408-899b-a10df6bf3587",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_2",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/514a790d-9798-4476-93e9-5cecb4b1c6a3/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "514a790d-9798-4476-93e9-5cecb4b1c6a3",
            "vnc_password": "testserver"
        }
    ]
}

Creating

POST /servers/

Creates a new virtual server or multiple servers. The minimial amount of information you need to set is as follows

Status Codes:
  • 201 – object created

Example request:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "testServerAcc",
            "vnc_password": "testserver"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "testServerAcc",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/05221547-3036-44c4-9418-0f0239992459/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "05221547-3036-44c4-9418-0f0239992459",
            "vnc_password": "testserver"
        }
    ]
}

Editing

PUT /servers/{uuid}/

Edits a server. Used also for attaching NIC’s and drives to servers. Note that if a server is running, only name, meta, and tags fields can be changed, and all other changes to the definition of a running server will be ignored.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "cpu": 2000,
    "mem": 536870912,
    "name": "test_server_updated",
    "vnc_password": "updated_password"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0e94a85a-d195-488e-b25d-ba6980fe21e4",
    "vnc_password": "updated_password"
}

Attach a drive

PUT /servers/{uuid}/

Attaching a drive is just an edit server operation.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "cpu": 2000,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": "b403f8e8-737d-4f9d-bb10-6de82508a6db"
        }
    ],
    "mem": 536870912,
    "name": "test_server_updated",
    "vnc_password": "updated_password"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": {
                "resource_uri": "/api/2.0/drives/b403f8e8-737d-4f9d-bb10-6de82508a6db/",
                "uuid": "b403f8e8-737d-4f9d-bb10-6de82508a6db"
            },
            "runtime": null
        }
    ],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0e94a85a-d195-488e-b25d-ba6980fe21e4",
    "vnc_password": "updated_password"
}

Metadata

It is possible to add arbitrary key-value data to a server definition. See Objects’ metadata field for more information.

Device channel

Device channel is used to specify the controller number and unit number for each attached drive. This is used so every time you reboot your virtual machine, the drive remains on the same place in your guest OS ( ex: /dev/sdc ) You specify the channel in the following format - {controller}:{unit} with the following limits for ide and virtio device types:

  • ide - 0:0, 0:1, 1:0, 1:1 ( total of 4 drives, max 2 units per controller, i.e 0-1)
  • virtio - 0:0, ..., 0:5, ..., 1:0, etc ( total of 1024 drives, max 6 units per controller i.e 0-5)

Deleting

Single server

DELETE /servers/{uuid}/

Deletes a single server.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/servers/05221547-3036-44c4-9418-0f0239992459/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Delete Server together with attached drives (recursive delete)

DELETE /servers/{uuid}/?recurse={recurse_option}

It is possible to delete a server together with it’s drives (recursive delete). There are three options: delete all attached drives, delete only disks(non-cdrom drives), or delete only attached cdroms. To recursively delete drives, supply a recurse URL parameter with a value as described in the following table:

Recurse option Effect
all_drives All attached drives regardless of media type will be deleted
disks Only attached drives with media type disk will be deleted
cdroms Only attached drives with media type cdrom will be deleted

Example request to delete a server with all attached drives:

A server is created with a cdrom and disk drives:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [
                {
                    "boot_order": null,
                    "dev_channel": "0:0",
                    "device": "ide",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/f2af396d-6821-4d8d-87ea-8c967468e220/",
                        "uuid": "f2af396d-6821-4d8d-87ea-8c967468e220"
                    },
                    "runtime": null
                },
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/f1888988-7754-4d89-a004-693fbf62e7a6/",
                        "uuid": "f1888988-7754-4d89-a004-693fbf62e7a6"
                    },
                    "runtime": null
                }
            ],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 268435456,
            "meta": {
                "description": "A full server with description"
            },
            "name": "test_acc_full_server",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:60:6f:c9:4d:64",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/ffb4ffc9-6b73-479b-a8d1-84cfc1c48dd1/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "ffb4ffc9-6b73-479b-a8d1-84cfc1c48dd1",
            "vnc_password": "tester"
        }
    ]
}

The following drives are available in the account:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/f2af396d-6821-4d8d-87ea-8c967468e220/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "f2af396d-6821-4d8d-87ea-8c967468e220"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/f1888988-7754-4d89-a004-693fbf62e7a6/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "f1888988-7754-4d89-a004-693fbf62e7a6"
        }
    ]
}

The server is recursively deleted with all drives:

DELETE /api/2.0/servers/ffb4ffc9-6b73-479b-a8d1-84cfc1c48dd1/?recurse=all_drives HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

After DELETE of the server the, drives attached to the server are deleted:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        }
    ]
}

Example request to delete a server with attached disk drives and leave CDROMs:

A server is created with a cdrom and disk drives:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [
                {
                    "boot_order": null,
                    "dev_channel": "0:0",
                    "device": "ide",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/f2af396d-6821-4d8d-87ea-8c967468e220/",
                        "uuid": "f2af396d-6821-4d8d-87ea-8c967468e220"
                    },
                    "runtime": null
                },
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/f1888988-7754-4d89-a004-693fbf62e7a6/",
                        "uuid": "f1888988-7754-4d89-a004-693fbf62e7a6"
                    },
                    "runtime": null
                }
            ],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 268435456,
            "meta": {
                "description": "A full server with description"
            },
            "name": "test_acc_full_server",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:60:6f:c9:4d:64",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/ffb4ffc9-6b73-479b-a8d1-84cfc1c48dd1/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "ffb4ffc9-6b73-479b-a8d1-84cfc1c48dd1",
            "vnc_password": "tester"
        }
    ]
}

The following drives are available in the account:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cf0af312-aeeb-4f3a-bf00-426d13126edf/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cf0af312-aeeb-4f3a-bf00-426d13126edf"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/0d5ef2eb-93f2-44fe-99fa-f85279dffa2b/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "0d5ef2eb-93f2-44fe-99fa-f85279dffa2b"
        }
    ]
}

The server is recursively deleted with all attached drives with media type disk:

DELETE /api/2.0/servers/93094d82-32d4-4b4e-a25a-0360369dbfee/?recurse=disks HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

After DELETE of the server, only drives with media type disk attached to the server are deleted. CDROMs are left intact:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 3
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/cf0af312-aeeb-4f3a-bf00-426d13126edf/",
            "status": "unmounted",
            "uuid": "cf0af312-aeeb-4f3a-bf00-426d13126edf"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        }
    ]
}

Server Runtime and Server Details

GET /servers/{uuid}/

Gets detailed information for server identified by server_uuid.

Status Codes:
  • 200 – no error

If the server is started the definition includes a runtime attribute. The runtime object contains information on, when the server was started, and runtime information about the server NICs, such as how much traffic went through the interface and what are the dynamic IPs assigned to the NIC. The NIC runtime is also available in the NIC definition of the running server.

Example request:

GET /api/2.0/servers/c6bffbaf-6e28-40f9-b2fd-7a71dd4eaab2/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": {
                "resource_uri": "/api/2.0/drives/64528400-2b45-40c5-b776-a8c92a34c596/",
                "uuid": "64528400-2b45-40c5-b776-a8c92a34c596"
            },
            "runtime": {
                "io": {
                    "bytes_read": 0,
                    "bytes_written": 0,
                    "count_flush": 0,
                    "count_read": 0,
                    "count_written": 0,
                    "total_time_ns_flush": 0,
                    "total_time_ns_read": 0,
                    "total_time_ns_write": 0
                }
            }
        }
    ],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:78:87:54:83:80",
            "model": "virtio",
            "runtime": {
                "interface_type": "public",
                "io": {
                    "bytes_recv": 0,
                    "bytes_sent": 0,
                    "packets_recv": 0,
                    "packets_sent": 0
                },
                "ip_v4": {
                    "resource_uri": "/api/2.0/ips/162.213.38.81/",
                    "uuid": "162.213.38.81"
                },
                "ip_v6": null
            },
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/c6bffbaf-6e28-40f9-b2fd-7a71dd4eaab2/",
    "runtime": {
        "active_since": "2014-06-05T09:51:08+00:00",
        "nics": [
            {
                "interface_type": "public",
                "io": {
                    "bytes_recv": 0,
                    "bytes_sent": 0,
                    "packets_recv": 0,
                    "packets_sent": 0
                },
                "ip_v4": {
                    "resource_uri": "/api/2.0/ips/162.213.38.81/",
                    "uuid": "162.213.38.81"
                },
                "ip_v6": null,
                "mac": "22:78:87:54:83:80"
            }
        ]
    },
    "smp": 1,
    "status": "running",
    "tags": [],
    "uuid": "c6bffbaf-6e28-40f9-b2fd-7a71dd4eaab2",
    "vnc_password": "testserver"
}

Server Actions

Start

POST /servers/{uuid}/action/?do=start

Starts a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/05221547-3036-44c4-9418-0f0239992459/action/?do=start HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "start",
    "result": "success",
    "uuid": "05221547-3036-44c4-9418-0f0239992459"
}

Warning

Servers have some default network restrictions, applied depending on your user state. Please refer to the default restrictions section the Firewall policies documentation

Stop

POST /servers/{uuid}/action/?do=stop

Stops a server with specific UUID. This action is equivalent to pulling the power cord of a physical server. For more graceful shutdown see ACPI Shutdown.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/05221547-3036-44c4-9418-0f0239992459/action/?do=stop HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "stop",
    "result": "success",
    "uuid": "05221547-3036-44c4-9418-0f0239992459"
}

ACPI Shutdown

POST /servers/{uuid}/action/?do=shutdown

Sends an ACPI shutdowns to a server with specific UUID for a minute. If the VM OS handles ACPI shutdown events (equivalent to pressing the power button), it will shutdown gracefully. As some operating systems don’t always handle single ACPI event the shutdown is sent every second for a minute. While the shutdown is initiated, the server is put into status stopping to prevent interfering actions. If after a minute the server has not powered off during this minute the status is returned to running to allow the user to Stop it. If the server shuts down successfully during the one minute period it will be switched to stopped status.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/d79eeec6-9cc5-4131-9f04-36961c267a74/action/?do=shutdown HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "shutdown",
    "result": "success",
    "uuid": "d79eeec6-9cc5-4131-9f04-36961c267a74"
}

Start in a separate availability group

It is possible to hint the system which servers are preferred to run on separate hardware host. See Starting Servers in a Different Availability Group (Start Avoid).

Open VNC Tunnel

POST /servers/{uuid}/action/?do=open_vnc

Opens a VNC tunnel to a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Note

VNC URL will be different each time you close/open the tunnel.

Example request:

POST /api/2.0/servers/80751bc7-37cc-48c1-bb08-fd04b46090bf/action/?do=open_vnc HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "open_vnc",
    "result": "success",
    "uuid": "80751bc7-37cc-48c1-bb08-fd04b46090bf",
    "vnc_url": "vnc://direct.lvs.cloudsigma.com:42714"
}

Close VNC Tunnel

POST /servers/{uuid}/action/?do=close_vnc

Closes a VNC tunnel to a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/80751bc7-37cc-48c1-bb08-fd04b46090bf/action/?do=close_vnc HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "close_vnc",
    "result": "success",
    "uuid": "80751bc7-37cc-48c1-bb08-fd04b46090bf"
}

Cloning

POST /servers/{uuid}/action/?do=clone
statuscode 202:Action accepted, execution is proceeding.

Clones a server. Does cascading clone of server drives, i.e. all disk drives attached to the server are cloned and attached to the new server. CDROM drives attached to the clone source are attached to the clone. IPs of the cloned server are set to DHCP. All other properties of the clone are equal to the original.

The optional body can contain a name attribute, which will be the name of the newly-cloned server and/or random_vnc_password boolean attribute which if set will generate a new vnc password for the new server.

Example clone source server:

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/39898df9-3ea5-49b8-b498-c856277214fe/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "39898df9-3ea5-49b8-b498-c856277214fe",
    "vnc_password": "testserver"
}

Example clone request:

POST /api/2.0/servers/39898df9-3ea5-49b8-b498-c856277214fe/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "test_cloned_server_name",
    "random_vnc_password": true
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [
        {
            "resource_uri": "/api/2.0/jobs/a94b1468-6f0b-4559-9057-17ebeb82d4a9/",
            "uuid": "a94b1468-6f0b-4559-9057-17ebeb82d4a9"
        }
    ],
    "mem": 536870912,
    "meta": {},
    "name": "test_cloned_server_name",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/5fe92884-f9e5-4a33-932d-c9de54b3bc28/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "5fe92884-f9e5-4a33-932d-c9de54b3bc28",
    "vnc_password": "9vCl6v3v"
}

Note

The name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information

Cloning with Drives on Different Storage (Avoid)

It is possible to hint the system which drives are preferred to be on separate physical storage host. See Creating Drives in a Different Availability Group (Create/Clone Avoid). I

Server NIC Configurations

The network interfaces are configured in the “nics” attribute. For more information on configuring network interfaces check Server Network Interfaces section.

Here is an example of defining a network interface with a dynamically assigned IP (for brevity only the “nics” attribute of the definitions is shown):

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "nics": [
        {
            "vlan": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:ef:1d:27:70:0b",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ]
}

Availability groups

It is possible to query which servers share common hardware hosts. See Server availability groups.

Advanced settings

On every server configuration there are a few advanced options you can setup.

{
    "cpus_instead_of_cores": false,
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false
}
  • cpus_instead_of_cores:
    • Type: true/false
    • Description: selects whether the SMP is exposed as cores of a single CPU or separate CPUs. This should be set to false for Windows, because there are license requirements for multiple CPUs.
  • enable_numa:
    • Type: true/false
    • Description: This option exposes the NUMA/CPU topology of the hypervisor to the virtual machine. It boosts performance for NUMA aware applications. The option should be set to true for servers with SMP bigger than 6, since this is the number of cores we have per NUMA node on the hypervisor. If set to true, cpus_instead_of_cores should also be set to true for Linux, because some Linux distributions do not support multiple NUMA nodes on multple CPU cores, but only on multiple CPUs.
  • hv_relaxed
    • Type: true/false
    • Description: Relax constraints on timers. This improves the behavior of VMs running Windows.
  • hv_tsc:
    • Type: true/false
    • Description: Enables more precise timers for Windows. This boost performance for timer specific code.

Warning

hv_relaxed and hv_tsc should be set to false for VMs running Linux

Server State Diagram

_images/ServerStates.png

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "context": {
            "default": true,
            "help_text": "Enable guest context serial device",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "cpu": {
            "default": null,
            "help_text": "Server's CPU Clock speed measured in MHz",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "cpu_model": {
            "choices": [
                "kvm64"
            ],
            "default": null,
            "help_text": "Choose the virtual CPU model, for mitigating compatibility issues between the guest operating system and the underlying host's CPU. If not specified, all of the hypervisor's CPU capabilities are passed directly to the virtual machine.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "cpus_instead_of_cores": {
            "default": false,
            "help_text": "Expose server SMPs as separate CPUs, instead of cores of a single CPU.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "drives": {
            "default": [],
            "fields": {
                "boot_order": {
                    "default": null,
                    "help_text": "Drive boot order",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "dev_channel": {
                    "default": null,
                    "help_text": "Device channel in format {controller:unit} ex. 0:1, 0:2, etc. Keep in mind that there are limits based on emulation type - for example ide can have up to 2 controllers, 2 units each.",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "device": {
                    "choices": [
                        "ide",
                        "virtio"
                    ],
                    "default": null,
                    "help_text": "Device emulation type",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "drive": {
                    "default": null,
                    "help_text": "Drive UUID",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "runtime": {
                    "default": "No default provided.",
                    "fields": {
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "bytes_written": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_flush": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_written": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_flush": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_write": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                }
                            },
                            "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Attached drive's runtime information",
                    "readonly": true,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "List of attached Drives to server",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "enable_numa": {
            "default": false,
            "help_text": "Expose NUMA topology to the server.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "hv_relaxed": {
            "default": false,
            "help_text": "Improve performance of Windows servers.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "hv_tsc": {
            "default": false,
            "help_text": "Improves performance of Windows servers with the trade off that the servers cannot be live migrated.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "mem": {
            "default": null,
            "help_text": "Server's Random Access Memory measured in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "meta": {
            "default": {},
            "help_text": "User assigned meta information for this server",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of server",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "nics": {
            "default": [],
            "fields": {
                "boot_order": {
                    "default": null,
                    "help_text": "Device boot order",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "firewall_policy": {
                    "default": null,
                    "help_text": "Firewall policy",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "ip_v4_conf": {
                    "default": null,
                    "fields": {
                        "conf": {
                            "choices": [
                                "dhcp",
                                "static",
                                "manual"
                            ],
                            "default": null,
                            "help_text": "Configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        },
                        "ip": {
                            "default": null,
                            "help_text": "An IP address reference. Only used in 'static' IP configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Public IPv4 configuration",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "ip_v6_conf": {
                    "default": null,
                    "fields": {
                        "conf": {
                            "choices": [
                                "dhcp",
                                "static",
                                "manual"
                            ],
                            "default": null,
                            "help_text": "Configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        },
                        "ip": {
                            "default": null,
                            "help_text": "An IP address reference. Only used in 'static' IP configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Public IPv6 configuration",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "mac": {
                    "default": null,
                    "help_text": "MAC address of the server NIC",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "model": {
                    "choices": [
                        "ne2k_isa",
                        "i82551",
                        "i82557b",
                        "i82559er",
                        "ne2k_pci",
                        "pcnet",
                        "rtl8139",
                        "e1000",
                        "virtio"
                    ],
                    "default": null,
                    "help_text": "Model of NIC",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "runtime": {
                    "default": "No default provided.",
                    "fields": {
                        "interface_type": {
                            "choices": [
                                "public",
                                "private"
                            ],
                            "default": null,
                            "help_text": "Type of interface",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_recv": {
                                    "default": 0,
                                    "help_text": "Bytes received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "bytes_sent": {
                                    "default": 0,
                                    "help_text": "Packets received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_recv": {
                                    "default": 0,
                                    "help_text": "Bytes sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_sent": {
                                    "default": 0,
                                    "help_text": "Packets sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                }
                            },
                            "help_text": "NIC runtime Input and Output data",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v4": {
                            "default": null,
                            "help_text": "Public IPv4 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v6": {
                            "default": null,
                            "help_text": "Public IPv6 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        }
                    },
                    "help_text": "NIC runtime information",
                    "readonly": true,
                    "required": false,
                    "type": "related"
                },
                "vlan": {
                    "default": null,
                    "help_text": "UUID of the private VLAN",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "The list of nics attached to this server",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "owner": {
            "default": null,
            "help_text": "UUID of the server owner",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "requirements": {
            "default": [],
            "help_text": "A collection of special requirements for this server",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "runtime": {
            "default": "No default provided.",
            "fields": {
                "active_since": {
                    "default": "No default provided.",
                    "help_text": "Datetime object representing the exact time the guest was started.",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "nics": {
                    "default": [],
                    "fields": {
                        "interface_type": {
                            "choices": [
                                "public",
                                "private"
                            ],
                            "default": null,
                            "help_text": "Type of interface",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_recv": {
                                    "default": 0,
                                    "help_text": "Bytes received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "bytes_sent": {
                                    "default": 0,
                                    "help_text": "Packets received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_recv": {
                                    "default": 0,
                                    "help_text": "Bytes sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_sent": {
                                    "default": 0,
                                    "help_text": "Packets sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                }
                            },
                            "help_text": "NIC runtime Input and Output data",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v4": {
                            "default": null,
                            "help_text": "Public IPv4 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v6": {
                            "default": null,
                            "help_text": "Public IPv6 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        },
                        "mac": {
                            "default": null,
                            "help_text": "MAC address of this NIC",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        }
                    },
                    "help_text": "The list of this server's NICs runtime",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                }
            },
            "help_text": "Runtime information of the guest",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "smp": {
            "default": null,
            "help_text": "Symmetric Multiprocessing (SMP) i.e. number of CPU cores",
            "readonly": false,
            "required": false,
            "type": "integer"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the guest.",
            "readonly": true,
            "required": false,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of server",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "vnc_password": {
            "default": null,
            "help_text": "VNC Password to connect to server",
            "readonly": false,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Server Context

Server context is a way for the VM to get information on the way it was set-up, i.e. get it’s definition. Server context is communicated over a virtual serial port device, which on UNIX-like operating system would usually appear as /dev/ttyS1 and on Windows as COM2. The serial port device for server context is the second serial device attached to the VM, because some UNIX operating systems configure a serial console on the first serial port.

Having the server definition accessible by the VM can be useful in various ways. For example it is possible to easily determine from within the VM, which network interfaces are connected to public and which to private network. Another use is to pass some data to initial VM setup scripts, like setting the hostname to the VM name or passing ssh public keys through server metadata.

At first sight, it might be confusing with the presence of both ‘server context’ and ‘server metadata’. ‘server metadata’ is really a subset of ‘server context’. The ‘server metadata’ itself is a key-value store for user-defined data on a server definition. The ‘server context’ on the other hand is one step above. It includes the full server definition, as well as the server metadata, along with attached drives definitions.

Context schema

The server context has almost the same schema as the /server/<uuid>/detail/ API request schema. It differs in that it lacks owner, subscriptions, status, and runtime information. The other difference is that the drives attributes are expanded to the corresponding /drive/<uuid>/detail/ which also lacks owner and runtime information. There is also a global_context attribute, which contains context available on all servers (see drive edit).

Setting up the virtual serial port

The virtual serial port device in not connected to a hardware device on the other side, so setting serial port hardware settings, such as baud rate and parity bits, does not affect the actual communication. However on Unix-like operating systems it may be necessary to set up the virtual terminal connected to the serial device. In general it is advisable to use the terminal in raw mode so that all characters are received uninterpreted. It is also important to not echo back received responses, because the may fill up the receive buffer, which may eject pending requests.

To set-up the terminal to raw mode on most unix systems one needs to the following command:

stty -F /dev/ttyS1 raw -echo

It is also possible to use cooked mode terminal for checking data on command line using standard utilities such as echo, read, and cat. As all responses are followed by newline and an End of Transmission character (usually represented as ^D or "\0x04"), so setting the terminal to cooked mode would make it interpret the EOT character as an End-Of-File condition, which makes it possible to use read and cat on the terminal device file (/dev/ttyS1) to receive the response. To set up cooked mode use the following command:

stty -F /dev/ttyS1 cooked -echo

If the default EOF character is different on your terminal it may be necessary to change it using:

stty -F /dev/ttyS1 cooked -echo eol ^D

Server Context Protocol

Requesting the complete server context

There is a simple protocol to retrieve the server context from the serial device. To request the whole server context one needs to send two newlines enclosed between inequality signs (aka pointy brackets, angle brackets). The newline can be either CRLF or just LF. In most programming languages the string to send will look like "<\n\n>".

The resulting response is a single-line json string representing the definition of the VM followed by newline (line feed character) and and an End of Transmission character (usually represented as ^D or "\0x04"). On Unix-like operating systems, if the terminal is set to cooked mode it is possible that the EOT character is interpreted as End-Of-File and is not present in the response.

The example below is for a server with the following definition:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "drives": [
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": "13168369-8450-4070-8909-444f56b747e8"
                }
            ],
            "mem": 1073741824,
            "meta": {
                "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"
            },
            "name": "test_server",
            "nics": [
                {
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "model": "virtio"
                }
            ],
            "vnc_password": "3022962f5d944b97"
        }
    ]
}

Below is an example of making a request, reading the result, and printing it on Linux in the bash shell:

#!/bin/bash

# set the terminal to cooked mode:
stty -F /dev/ttyS1 cooked -echo eol ^D
# use -e to parse newline escapes, and -n to remove the trailing newline:
echo -en "<\n\n>" > /dev/ttyS1
# read with timeout of 3 seconds and print the value which is put in the variable READVALUE
read -t 3 READVALUE < /dev/ttyS1 && echo $READVALUE

Examples:

Request command. Including a flushing read before the actual request with echo:

v=$(read -t 13 READVALUE < /dev/ttyS1 && echo $READVALUE & sleep 1; echo -en "<\n\n>" > /dev/ttyS1; wait %1); echo $v

Result:

{"uuid": "e83c79b3-ef07-4b8e-968e-dff5c386a053", "requirements": [], "name": "test_server", "cpus_instead_of_cores": false, "tags": [], "mem": 1073741824, "nics": [{"boot_order": null, "vlan": null, "ip_v4_conf": {"ip": {"uuid": "162.213.38.123", "tags": [], "nameservers": ["69.194.139.62", "178.22.66.167", "178.22.71.56"], "netmask": 24, "meta": {}, "gateway": "162.213.38.1"}, "conf": "dhcp"}, "mac": "22:51:c1:18:7b:4a", "model": "virtio", "ip_v6_conf": null}], "enable_numa": false, "global_context": {}, "drives": [{"device": "virtio", "dev_channel": "0:0", "drive": {"uuid": "13168369-8450-4070-8909-444f56b747e8", "tags": [], "media": "disk", "name": "test_clone_1", "meta": {"description": "", "install_notes": ""}, "allow_multimount": false, "licenses": [], "affinities": [], "size": 12348030976}, "boot_order": 1}], "cpu_model": null, "hv_relaxed": false, "hv_tsc": false, "meta": {"ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"}, "smp": 1, "cpu": 1000, "vnc_password": "3022962f5d944b97"}

Requesting a partial server context or a single value

To request a part of the definition json one can provide a path in the request. The path contains strings or integers separated by a forward slash (/). To request only the part of the json which is the NICs definitoins one can request the path “/nics”. To request an element from a list value one can use an index in the path. Note that counting starts from 0. For example to get the defintion of the first network interface one can use the following path “/nics/0”.

If the value of pointed to the path is a leaf value (it does not contain a json object or alist), it is returned without the surrounding quotes so requesting <\nname\n> from a server named “myserver” would return:

myserver\n\0xd

and NOT:

"myserver"\n\0xd

Be advised that the returned strings won’t contain surrounding quotes but ASCII control characters will be backslash escaped. For example line-feed will become \n, carriage-return will become \r, and tab will become \t. Also there is no way to represent null json values so this will be converted to an empty string. Make sure that you parse the escaped characters if you need the original unescaped text in your scripts. An easy way to do it on UNIX-like OS is to use echo -e $READVALUE.

Examples:

Request command. Including a flushing read before the actual request with echo:

v=$(read -t 13 READVALUE < /dev/ttyS1 && echo $READVALUE & sleep 1; echo -en "<\nname\n>" > /dev/ttyS1; wait %1); echo $v

Result:

test_server

Passing information to the VM

The most suitable place to store information for passing to the VM through the context interface is the server meta field, or drive meta. Check Objects’ metadata field for more information on editing the meta field.

For example in the server definition from above examples, the meta looks like:

{
    "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"
}

One can retrieve the ssh_public_key from the meta from within the VM using:

v=$(read -t 13 READVALUE < /dev/ttyS1 && echo $READVALUE & sleep 1; echo -en "<\n/meta/ssh_public_key\n>" > /dev/ttyS1; wait %1); echo $v

Result:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal

Note that there isn’t anything special about the ssh_public_key attribute of the metadata. It can be stored under any other key in the server metadata, as long as client software is aware where to look for it. It is also possible to store the key in one of the attached drives’ meta.

Global context

Global context can be used to hold server context information common to all user’s servers. Like meta field on servers, it can store arbitrary key-value pairs, but as the name suggests it is global for the user account, and the same for all servers.

Global context is centrally managed at the /global_context/ API url. Within the VM context it resides in the global_context attribute of the server server definition.

Get or update global context

GET /global_context/
POST /global_context/

Example:

Add a value to the global context.

POST /api/2.0/global_context/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "new_global_key": "new_global_val"
}

The resulting global context is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "new_global_key": "new_global_val"
}

Using the server from examples above, we can check the context from the server shell:

Request command:

v=$(read -t 13 READVALUE < /dev/ttyS1 && echo $READVALUE & sleep 1; echo -en "<\n\n>" > /dev/ttyS1; wait %1); echo $v

Result:

{"uuid": "e83c79b3-ef07-4b8e-968e-dff5c386a053", "requirements": [], "name": "test_server_renamed", "cpus_instead_of_cores": false, "tags": [], "mem": 1073741824, "nics": [{"boot_order": null, "vlan": null, "ip_v4_conf": {"ip": {"uuid": "162.213.38.123", "tags": [], "nameservers": ["69.194.139.62", "178.22.66.167", "178.22.71.56"], "netmask": 24, "meta": {}, "gateway": "162.213.38.1"}, "conf": "dhcp"}, "mac": "22:51:c1:18:7b:4a", "model": "virtio", "ip_v6_conf": null}], "enable_numa": false, "global_context": {"new_global_key": "new_global_val"}, "drives": [{"device": "virtio", "dev_channel": "0:0", "drive": {"uuid": "13168369-8450-4070-8909-444f56b747e8", "tags": [], "media": "disk", "name": "test_clone_1", "meta": {"description": "", "install_notes": ""}, "allow_multimount": false, "licenses": [], "affinities": [], "size": 12348030976}, "boot_order": 1}], "cpu_model": null, "hv_relaxed": false, "hv_tsc": false, "meta": {"another_key": "a value or something", "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"}, "smp": 1, "cpu": 1000, "vnc_password": "3022962f5d944b97"}

Notice how the value of the global_context changed:

{
    "global_context": {
        "new_global_key": "new_global_val"
    }
}

Server Network Interfaces

Private and Public Network Interfaces

There are three configurations for any one NIC that determines how that NIC behaves. Not all combinations of configuration are valid:

  • vlan: Private Network
  • ip_v4_conf: Public IP v4 Network, either static, DHCP, or manually assigned.
  • ip_v6_conf: Public IP v6 Network, either static, DHCP, or manually assigned.
Configurations Result
vlan ip_v4_conf ip_v6_conf  
True True True Error: Cannot assign all configs on a NIC
True True False Error: Cannot assign both Private and Public on a NIC
True False True Error: Cannot assign both Private and Public on a NIC
True False False Private network assigned
False True True Both IP v4 and v6 assigned
False True False Only IP v4 assigned
False False True Only IP v6 assigned
False False False No config assigned

IP Assignment for Public Interfaces

Assignment of IPs on private network interface is up to the user.

For public network interfaces it is possible to configure the way the address is assigned by setting the “conf” attribute on the ip_v4_conf or ip_v6_conf object:

“dhcp”:

The address is chosen by the system at boot time and assigned through DHCP. On each reboot the VM may get a different address. It is an error to specify the IP address for “conf”: “dhcp”. It is possible get the currently assigned dynamic IP of a NIC from the server runtime of a running server.

{
    "ip_v4_conf": {
        "conf": "dhcp"
    }
}
“static”:

The address is chosen and specified by the user. It is assigned to the NIC through DHCP and does not change between reboots. The “ip” attribute is mandatory and an IP address can be assigned from the addresses owned by the user.

{
    "ip_v4_conf": {
        "conf": "static",
        "ip": "185.12.6.183"
    }
}
“manual”:

There is no address specified for the NIC, and the user has to specify the IP address from within the VM. When this setting is used, the NIC is allowed to use all IPs for which the user has subscription. This “conf” can be used to assign multiple IPs to the same NIC.

{
    "ip_v4_conf": {
        "conf": "manual"
    }
}

Note

The cloud firewall does not allow traffic to/from IPs which are not owned or not assigned to the VM. The only exception is for “manual” conf where the VM is allowed to use any of the IPs which are owned by the user (the user has a subscriptions for them).

MAC Addresses

Newly created NICs have their mac address randomly generated.

Note

All traffic from a MAC address different from the assigned by the system is stopped by the cloud firewall, so users should no attempt to change their MACs from within their VM.

In order to update a NIC definition, the definition should have its “mac” attribute filled in. If on “nics” list update a MAC address disappears from the list, the corresponding NIC is deleted. If a MAC appears in the new list, the corresponding nic is updated, and if no MAC is specified on a NIC, a new NIC is created. It is an error to attempt to specify a MAC address which was not previously in the “nics” list.

The order of NICs in the “nics” attribute is important, because it is also the order in which nics are presented to the VM. It is possible to rearrange NICs by rearranging their orded in the “nics” list.

NIC Models

The “model” attribute specifies the model of the emulated network card. It is recommended to use virtio, whenever possible (when drivers for virtio are available for the VM operating system).

Model Bus Speed Description
e1000 PCI 1Gb/s Intel Gigabit Ethernet
i82551 ? ? ?
i82557b ? ? ?
i82559er ? ? ?
ne2k_pci PCI 10Mb/s NE2000
pcnet ? ? ?
rtl8139 ? 10/100Mb/s Realtek Fast Ethernet
virtio PCI 1Gb/s Virtual High Performance Ethernet card (see Virtio)

Reference: Wikibooks QEMU/Devices/Network.

NIC Runtime

When a server is running, the server definition provides information on the currently assigned dynamic IP and the data traffic made through the NIC. See server runtime for more details.

Examples

Example 1 - Private Network assigned to server:

Definition with all other values default:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "vlan": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Result:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:ef:1d:27:70:0b",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 2 - Dynamic IP v4 (DHCP) assigned to NIC with e1000 model:

Definition with model set to ‘e1000’:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "model": "e1000"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Result:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:5f:87:fd:00:b1",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 3 - Update nics:

Here is an example of a server with two nics:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

In order to change the IP configuration of the NIC the definitions should have a MAC specified. Notice that in order to not delete the other NIC both NICs should be put in the request:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": "185.12.6.183"
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

The result is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 4 - Rearrange nics:

In order to rearrange the NICs of the server definition from Example 3, the definition should just be updated with different order of NICs (NICs are recognized by their MAC):

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

The resulting “nics” are:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Notice that the private and public NICs changed order compared to Example 3.

Example 5 - Delete a NIC and change type of the other:

In order to change a NIC from private to public just remove the “vlan” field and “ip_v4_conf” field. This can also be combined with deletion of the other interface. Using the NICs from Example 4 here is how to delete the public NIC and change the private NIC to public:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "mac": "22:a5:f0:db:fe:da"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Notice that the NIC has the same MAC as the private NIC from Example 4, but is configured with DHCP.

Networking

VLAN

Allowed HTTP methods

Method Description
GET get / list VLANs
PUT edit VLANs meta

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /vlans/

Gets the list of VLANs to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/vlans/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ]
}

Detailed listing

GET /vlans/detail/
statuscode 200:no error

Example request:

GET /api/2.0/vlans/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "grantees": [],
            "meta": {},
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "servers": [],
            "subscription": {
                "id": 7272,
                "resource_uri": "/api/2.0/subscriptions/7272/"
            },
            "tags": [],
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ]
}

Get single VLAN

GET /vlans/(uuid: vlan_uuid)/
statuscode 200:no error

Example request:

GET /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "grantees": [],
    "meta": {},
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
    "servers": [],
    "subscription": {
        "id": 7272,
        "resource_uri": "/api/2.0/subscriptions/7272/"
    },
    "tags": [],
    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
}

Creating

New VLANs are created by buying a subscription. See Subscriptions.

Editing

Currently only VLAN meta field can be edited.

PUT /vlans/(uuid: vlan_uuid)/
statuscode 200:no error

Example request:

PUT /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    },
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
    "servers": [],
    "subscription": {
        "id": 7272,
        "resource_uri": "/api/2.0/subscriptions/7272/"
    },
    "tags": [],
    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
}

Metadata

It is possible to add arbitrary key-value data to a VLAN definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The VLAN will disappear when the subscription for it expires.

Attaching To servers

A VLAN can be attached to multiple servers. See Server Network Interfaces for more information on using VLANs in NIC configurations.

IPs

The IP object, contains the actual IP in it’s uuid attribute.

The list of IPs includes the IPs that are owned (subscribed to) by the user, and the IPs which are dynamically assigned to user’s servers. The owned IP’s are differentiated by dynamically received IPs by the fact that they have a subscription attached to them (their subscription attribute is not empty).

The detailed listing includes more information about the IP object, such as netmask, nameservers, and gateway which will be set on the NIC. The netmask value is in CIDR notation (/24 for a 255.255.255.0 mask). The nameservers attribute contains a list of DNS servers, which will be assigned through DHCP, and the gateway attribute contains the IP of the default gateway for the current IP.

Allowed HTTP methods

Method Description
GET get / list IPs
PUT edit IP metadata

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /ips/

Gets the list of IPSs to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/ips/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "uuid": "185.12.6.183"
        }
    ]
}

Detailed listing

GET /ips/detail/
statuscode 200:no error

Example request:

GET /api/2.0/ips/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "gateway": "185.12.6.1",
            "grantees": [],
            "meta": {},
            "nameservers": [
                "69.194.139.62",
                "178.22.66.167",
                "178.22.71.56"
            ],
            "netmask": 24,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "subscription": {
                "id": 7273,
                "resource_uri": "/api/2.0/subscriptions/7273/"
            },
            "tags": [],
            "uuid": "185.12.6.183"
        }
    ]
}

Get single IP

GET /ips/(uuid: ip_uuid)/
statuscode 200:no error

Example request:

GET /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {},
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Creating

New IPs are created by buying a subscription. See Subscriptions.

Editing

Currently only IP meta field can be edited.

PUT /ips/(uuid: ip_uuid)/
statuscode 200:no error

Example request:

PUT /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    },
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Metadata

It is possible to add arbitrary key-value data to an IP definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The IP will disappear when the subscription for it expires.

Attaching To servers

An IP can be attached to a single server. To check whether IP is currently attached to a server look at the attribute on the object in the detailed listing or on single object retrieval. If server is empty, then the IP is not attached to a server and can be used for static IP configuration. See Server Network Interfaces for more information on using IPs in NIC configurations.

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put"
    ],
    "allowed_list_http_methods": "get",
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "owner": {
            "default": null,
            "help_text": "VLAN owner",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "servers": {
            "default": [],
            "help_text": "Servers in this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "subscription": {
            "default": null,
            "help_text": "Subscription related to this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "VLAN UUID",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Firewall Policies

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /fwpolicies/

Gets the list of firewall policies to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Detailed listing

GET /fwpolicies/detail/

Gets a detailed list of firewall policies to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Create

POST /fwpolicies/

Creates a firewall policy.

Status Codes:
  • 201 – no error

Example request - minimal:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {}
    ]
}

Example response - minimal:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        }
    ]
}

This is the minimal data required to create a policy. It is blank one ( does not contain any rules ), but you can use it to attach it to a couple of servers and edit it later to match your needs.

Example request - full:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "My awesome policy",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23"
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24"
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp"
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55"
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp"
                }
            ]
        }
    ]
}

Example response - full:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

This is a more useful firewall policy. The rules are applied in the order they are stated.

Note

  • The IP and port fields support ”!” prefix, which specifies “NOT” ( ex. ”!192.168.1.1” ).
  • You can specify port ranges with ”:” ( ex. “1:1024” or ”!1:1024”)
  • The IP fields support subnet definition using the CIDR notation ( ex. “192.168.1.1/24” )

Editing

PUT /fwpolicies/{uuid}/

Update an existing firewall policy

Warning

Changes are applied every 30 seconds to all running servers with nics that have the policy attached.

Status Codes:
  • 200 – no error
Example policy:
{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "accept",
            "comment": "Allow SSH traffic to the VM from our office in Dubai",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": "172.66.32.0/24",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all other SSH traffic to the VM",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
            "direction": "in",
            "dst_ip": null,
            "dst_port": null,
            "ip_proto": "udp",
            "src_ip": "!172.66.32.55/32",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "!1:1024",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update request:
PUT /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}

Delete

DELETE /fwpolicies/{uuid}/

Delete a firewall policy

Warning

Only policies attached to servers in status stopped can be deleted.

Status Codes:
  • 204 – no content, object is deleted

Example request:

DELETE /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Attach policy to a server

Attaching a policy is done by specifying the policy uuid in the field firewall_policy on the server’s NIC, using the create or edit server calls

{
    "cpu": 1000,
    "mem": 536870912,
    "name": "FirewalledServer",
    "nics": [
        {
            "firewall_policy": "abb98bcb-2d3c-4758-b59c-3094b54b5c9e",
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "model": "virtio"
        }
    ],
    "vnc_password": "testserver"
}

Warning

Firewall policies are only applied when attached to your server’s public network interfaces.

Default restrictions

Depending on your account’s current state, the following restrictions are applied:

  • Level 0 - for REGULAR users:
    Running servers have limits set on originating broadcast and multicast traffic:
    • broadcast - limited to 5 packets/second with burst of 100
    • multicast - limited to 10 packets/second with burst of 100
  • Level 1 - for TRIAL users:

    Running servers cannot open communication channels to ports 22, 23, 25, 7777, 43594, 43595 and 25565

  • Level 2 - for GUEST and NEW users:

    Running servers can only send ICMP requests, request a DHCP IP, query a DNS server and send requests to TCP port 80 and 443 ( usually HTTP and HTTPS )

Each restriction level applies all the rules from the previous one - i.e. Level 0 rules are applied to Level 1, etc. Please contact support if any of these restrictions breaks your workflow.

Note

When converting from one user type to another, restrictions are automatically adjusted - no need to powercycle your running servers.

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "meta": {
            "default": {},
            "help_text": "User assigned meta information for this policy",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the firewall policy",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the policy",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "rules": {
            "default": [],
            "fields": {
                "action": {
                    "choices": [
                        "drop",
                        "accept"
                    ],
                    "default": null,
                    "help_text": "Action to be taken",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "comment": {
                    "default": null,
                    "help_text": "Optional rule comment",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "direction": {
                    "choices": [
                        "in",
                        "out",
                        "both"
                    ],
                    "default": null,
                    "help_text": "Packet direction",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "dst_ip": {
                    "default": null,
                    "help_text": "Destination IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "dst_port": {
                    "default": null,
                    "help_text": "Destination port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "ip_proto": {
                    "choices": [
                        "tcp",
                        "udp"
                    ],
                    "default": null,
                    "help_text": "IP protocol",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_ip": {
                    "default": null,
                    "help_text": "Source IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_port": {
                    "default": null,
                    "help_text": "Source port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                }
            },
            "help_text": "List of rules to be applied for this policy",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "servers": {
            "default": [],
            "help_text": "Servers which have nics with this policy applied",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the policy",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Tags

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /tags/

Gets the list of tags to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/tags/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        },
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

List single tag

GET /tag/(uuid: tag_uuid)/

Gets detailed information for tag identified by tag_uuid.

statuscode 200:no error

Example request:

GET /api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "vlans",
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
            "uuid": "f52db291-f754-4434-acac-77268cbac94f"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "ips",
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "uuid": "185.12.6.183"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

Creating

POST /tags/

Creates a new tag or multiple tags.

statuscode 201:object created

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "MyGroupOfThings"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        }
    ]
}

It is possible to add resources to a tag at creation time. Just specify their UUIDs the resources list:

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "TagCreatedWithResource",
            "resources": [
                "f52db291-f754-4434-acac-77268cbac94f",
                "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a",
                "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd",
                "185.12.6.183",
                "96537817-f4b6-496b-a861-e74192d3ccb0"
            ]
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

Editing

PUT /tags/{uuid}/

Edits a tag. It is possible to add or remove resources to a tag by replacing the resources list with a new one:

statuscode 200:no error

Example request:

PUT /api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "TagCreatedWithResource",
    "resources": [
        "00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f",
        "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "snapshots",
            "resource_uri": "/api/2.0/snapshots/00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f/",
            "uuid": "00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

It is also possible to edit the tags on the resource itself by replacing the tags list. For example here is how to add a tag from a server:

Example request:

PUT /api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        "7b102579-e850-47cf-adf9-9c1a499b08f8",
        "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
    ],
    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a",
    "vnc_password": "pass"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        },
        {
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ],
    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a",
    "vnc_password": "pass"
}

Deleting

DELETE /tags/{uuid}/

Deletes a single tag.

statuscode 204:No content, object deletion started.

Example request:

DELETE /api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Filter Servers, Drives, IPs or VLANs listing by tag

GET /tags/{uuid}/{resource_type}/

Lists the objects of the given resource_type which is one of ‘servers’, ‘drives’, ‘ips’, ‘vlans’.

statuscode 200:no error

Example request:

GET /api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "name": "test_server2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": {
                "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
            },
            "runtime": null,
            "status": "stopped",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        }
    ]
}

Jobs

Jobs are used to track progress of long running tasks. A good example for a long running task is cloning of drives and servers. Depending on the current cloud resource usage and the users preferences ( Creating Drives in a Different Availability Group (Create/Clone Avoid) ), a drive clone operation can take a while.

Currently, the operations that create a job for tracking are:
  • Drive cloning
  • Server cloning

How it works

Drive cloning

After successfully starting a cloning operation via the API, you will receive the definition of the newly created drive. All drives have a jobs field, containing references to the all the long running tasks executed on them. The destination, since it is a newly created drive, references only 1 job - the currently running one. The source might contain more jobs, depending on how many times it was cloned. History of completed jobs is kept for 3 days. Older jobs are discarded.

Example clone request:

POST /api/2.0/drives/963e3f37-572a-4e40-b70f-06f093ea7eb5/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "name": "test_drive_y",
    "storage_type": "dssd"
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/",
                    "uuid": "6c809fa7-f797-4d0f-bbfb-b1b9ba737dda"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_y",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/842e4c44-75a2-4d81-b812-9bc63d3be11e/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "842e4c44-75a2-4d81-b812-9bc63d3be11e"
        }
    ]
}

Using the the jobs field we could examine how is our cloning operation doing:

Example request:

GET /api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "children": [],
    "created": "2014-06-05T09:45:08.003595+00:00",
    "data": {
        "progress": 100
    },
    "last_modified": "2014-06-05T09:45:12.941760+00:00",
    "operation": "drive_clone",
    "resource_uri": "/api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/",
    "resources": [
        "/api/2.0/drives/842e4c44-75a2-4d81-b812-9bc63d3be11e/",
        "/api/2.0/drives/963e3f37-572a-4e40-b70f-06f093ea7eb5/"
    ],
    "state": "success",
    "uuid": "6c809fa7-f797-4d0f-bbfb-b1b9ba737dda"
}

The interesting field here is data.progress. 100 means the job has finished.

Server cloning

Cloning a server is a bit more complex. Since servers generally contain drives, drives must also be cloned. That is why jobs support sub-jobs. When you send a clone server request, you receive the definition of the newly created server. It also has a jobs field containing the definitions of jobs and sub-jobs.

Example clone request:

POST /api/2.0/servers/39898df9-3ea5-49b8-b498-c856277214fe/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "test_cloned_server_name",
    "random_vnc_password": true
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [
        {
            "resource_uri": "/api/2.0/jobs/a94b1468-6f0b-4559-9057-17ebeb82d4a9/",
            "uuid": "a94b1468-6f0b-4559-9057-17ebeb82d4a9"
        }
    ],
    "mem": 536870912,
    "meta": {},
    "name": "test_cloned_server_name",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/5fe92884-f9e5-4a33-932d-c9de54b3bc28/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "5fe92884-f9e5-4a33-932d-c9de54b3bc28",
    "vnc_password": "9vCl6v3v"
}

Each job has children field with containing its sub-jobs. Note that each sub-job contains a children field, too. Meaning that a sub-job could have a sub-jobs, too.

Example request:

GET /api/2.0/jobs/4e1944be-a078-4ead-9d19-5f8823a84d42/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "children": [
        {
            "children": [],
            "created": "2014-06-05T09:50:06.771415+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T09:50:12.817209+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/5cf1a9e0-c019-4022-9ca5-08af64fa5105/",
            "resources": [
                "/api/2.0/drives/4f41610b-b73b-49f0-a7c8-2e5cd110eb31/",
                "/api/2.0/drives/eaa0b214-7f8c-446d-9d6b-1c106fcd9aba/"
            ],
            "state": "success",
            "uuid": "5cf1a9e0-c019-4022-9ca5-08af64fa5105"
        }
    ],
    "created": "2014-06-05T09:50:06.436976+00:00",
    "data": {
        "progress": 100
    },
    "last_modified": "2014-06-05T09:50:12.726357+00:00",
    "operation": "server_clone",
    "resource_uri": "/api/2.0/jobs/4e1944be-a078-4ead-9d19-5f8823a84d42/",
    "resources": [
        "/api/2.0/servers/3ee19ba9-fd1a-435b-9dbf-559d188fba90/",
        "/api/2.0/servers/810850e5-593b-4c21-af9e-a7cadac5b79c/"
    ],
    "state": "success",
    "uuid": "4e1944be-a078-4ead-9d19-5f8823a84d42"
}

List all jobs

All jobs can be listed and examined quite easily.

Example request:

GET /api/2.0/jobs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 500
    },
    "objects": [
        {
            "children": [],
            "created": "2014-06-05T00:27:12.890638+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T00:27:17.537618+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/654b3d26-0b4a-41ff-b166-741adc9fcc61/",
            "resources": [],
            "state": "success",
            "uuid": "654b3d26-0b4a-41ff-b166-741adc9fcc61"
        },
        {
            "children": [],
            "created": "2014-06-04T13:48:30.146021+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:48:30.182588+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/2bb2929e-75e0-47ea-a7ef-88ae5c205bca/",
            "resources": [],
            "state": "success",
            "uuid": "2bb2929e-75e0-47ea-a7ef-88ae5c205bca"
        },
        {
            "children": [],
            "created": "2014-06-04T19:27:22.929792+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T19:27:28.194541+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/6d9eef6c-7b7b-412f-b0c8-b31acfa31b4b/",
            "resources": [],
            "state": "success",
            "uuid": "6d9eef6c-7b7b-412f-b0c8-b31acfa31b4b"
        },
        {
            "children": [],
            "created": "2014-06-05T05:20:06.808650+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T05:20:07.714198+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
        },
        {
            "children": [],
            "created": "2014-06-04T09:44:52.922093+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T09:44:59.151935+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/51f17911-5db7-414a-b291-6a26d99c7af4/",
            "resources": [],
            "state": "success",
            "uuid": "51f17911-5db7-414a-b291-6a26d99c7af4"
        },
        {
            "children": [],
            "created": "2014-06-05T08:27:17.837077+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T08:27:22.451556+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/98be68fd-bc5b-42fd-ba42-2a197e7ad7bb/",
            "resources": [],
            "state": "success",
            "uuid": "98be68fd-bc5b-42fd-ba42-2a197e7ad7bb"
        },
        {
            "children": [],
            "created": "2014-06-04T10:37:08.377980+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T10:37:09.264198+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
        },
        {
            "children": [],
            "created": "2014-06-04T14:47:51.859179+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T14:47:52.695159+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
        },
        {
            "children": [],
            "created": "2014-06-04T12:08:35.939653+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T12:08:42.703768+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/9df9bccb-7a7a-4dc3-afbe-65614ae68828/",
            "resources": [],
            "state": "success",
            "uuid": "9df9bccb-7a7a-4dc3-afbe-65614ae68828"
        },
        {
            "children": [],
            "created": "2014-06-04T14:54:38.461484+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T14:54:44.194807+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/a71f63ac-940c-4b1b-b536-d98b7ebcdd1f/",
            "resources": [],
            "state": "success",
            "uuid": "a71f63ac-940c-4b1b-b536-d98b7ebcdd1f"
        },
        {
            "children": [],
            "created": "2014-06-04T10:15:45.013901+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T10:15:49.998849+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/b75498db-c630-4eae-9d4c-545b55c9f80c/",
            "resources": [],
            "state": "success",
            "uuid": "b75498db-c630-4eae-9d4c-545b55c9f80c"
        },
        {
            "children": [],
            "created": "2014-06-04T18:23:05.924797+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T18:23:07.201011+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/5ca591ad-4973-486f-865e-f649924ec8a9/",
            "resources": [],
            "state": "success",
            "uuid": "5ca591ad-4973-486f-865e-f649924ec8a9"
        },
        {
            "children": [],
            "created": "2014-06-04T13:22:41.878643+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:22:43.423951+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/1590cc04-a04d-47c6-aeea-e686fba11480/",
            "resources": [],
            "state": "success",
            "uuid": "1590cc04-a04d-47c6-aeea-e686fba11480"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-04T09:22:19.895663+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-04T09:22:21.182049+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/b3c8791a-7163-47fd-871d-ce7e74cdea22/",
                    "resources": [],
                    "state": "success",
                    "uuid": "b3c8791a-7163-47fd-871d-ce7e74cdea22"
                }
            ],
            "created": "2014-06-04T09:22:19.229671+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T09:22:21.090352+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/2f9fb6cb-d879-4bfb-afaa-0e7e9e8c8171/",
            "resources": [],
            "state": "success",
            "uuid": "2f9fb6cb-d879-4bfb-afaa-0e7e9e8c8171"
        },
        {
            "children": [],
            "created": "2014-06-05T09:45:29.984652+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T09:45:34.243982+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/a34a8179-f6c1-4a0c-8d96-f0d727017807/",
            "resources": [],
            "state": "success",
            "uuid": "a34a8179-f6c1-4a0c-8d96-f0d727017807"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-05T07:22:35.318791+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-05T07:22:36.437933+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/b548f9cc-9290-4c44-880a-688511964088/",
                    "resources": [],
                    "state": "success",
                    "uuid": "b548f9cc-9290-4c44-880a-688511964088"
                }
            ],
            "created": "2014-06-05T07:22:34.982635+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T07:22:36.341483+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/b60c32a1-6c07-4ba0-bffa-ef7a5b51829b/",
            "resources": [],
            "state": "success",
            "uuid": "b60c32a1-6c07-4ba0-bffa-ef7a5b51829b"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-04T13:49:17.336222+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-04T13:49:22.411035+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/2f575e30-3a2c-45a2-bc46-0dd6e73ba5bb/",
                    "resources": [],
                    "state": "success",
                    "uuid": "2f575e30-3a2c-45a2-bc46-0dd6e73ba5bb"
                }
            ],
            "created": "2014-06-04T13:49:16.986663+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:49:22.312955+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/f1deb190-bb8f-4bc2-8013-ca6f69e4f481/",
            "resources": [],
            "state": "success",
            "uuid": "f1deb190-bb8f-4bc2-8013-ca6f69e4f481"
        },
        {
            "children": [],
            "created": "2014-06-04T16:31:41.972433+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T16:31:49.636223+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/eb93dffd-d457-471c-a812-f970c39aef65/",
            "resources": [],
            "state": "success",
            "uuid": "eb93dffd-d457-471c-a812-f970c39aef65"
        },
        {
            "children": [],
            "created": "2014-06-05T06:22:43.214966+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T06:22:44.265751+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/4a616d17-8e57-4756-b186-211539405d8d/",
            "resources": [],
            "state": "success",
            "uuid": "4a616d17-8e57-4756-b186-211539405d8d"
        },
        {
            "children": [],
            "created": "2014-06-04T15:29:03.093430+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T15:29:09.318627+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/68609b60-7f6f-4890-8940-b9e0c8d2af77/",
            "resources": [],
            "state": "success",
            "uuid": "68609b60-7f6f-4890-8940-b9e0c8d2af77"
        }
    ]
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "children": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Background jobs, initiated by this job.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "created": {
            "blank": false,
            "default": "2014-06-05T09:46:41.793232+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "data": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Meta information related to this background job's execution.",
            "nullable": true,
            "readonly": false,
            "type": "object",
            "unique": false
        },
        "last_modified": {
            "blank": false,
            "default": "2014-06-05T09:46:41.793249+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "operation": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "resources": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Resources linked to this background job.",
            "nullable": true,
            "readonly": false,
            "type": "list",
            "unique": false
        },
        "state": {
            "blank": false,
            "default": "started",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        }
    },
    "filtering": {
        "state": 1
    },
    "ordering": [
        "-last_modified"
    ]
}

Objects’ metadata field

Objects, such as servers, drives, IPs, and VLANs have a meta field. This field can be used to store arbitrary information in key-value form. There is no predefined structure for the meta attribute, only keys are limited to 32 characters, and values should be strings. The Web UI uses the meta to store drive and server descriptions.

Note that the whole meta is updated completely so all old key-value pairs should be present in new definition, when updating meta, unless they are to be deleted.

Server’s metadata fields with special meaning

  • ssh_public_key is filled with the contents of the “SSH Key” field from the server’s properties section
  • cloudinit-user-data if available (and cloud-init 0.7.5 or newer is installed on the server) this field should contains valid cloud-init user data, that will be taken into account from the cloud-init
  • base64_fields contains comma-separated meta keys in the metadata that are encoded in base64. This feature is useful when a meta field has more than one lines of text. cloud-init (0.7.5 or newer) for example will automatically decode from base64 the contents of cloudinit-user-data if the name of the meta key is in base64_fields

Drive’s metadata fields with special meaning

When drive is cloned from the library we copy its Metadata to the new drive’s meta as:

  • os - drive’s operating system (e.g. GNU/Linux, BSD, Windows...)
  • arch - the architecture of the OS (e.g. 32-bit or 64-bit)
  • distribution - for GNU/Linux and BSD operating systems (e.g. Debian, Fedora, FreeBSD...)
  • version - distribution’s version (if any)
  • default_user - used in pre-installed images in order to specify the default user in the installed OS
  • install notes - used if the image is not pre-installed
  • url - URL to the official website of the OS
  • description - description of what the drive contains
  • image_type - type of the image on the drive (e.g. Live CD, Install CD, Pre-install)
  • category - states what this image is most suitable for (e.g. dbserver, webserver, router, networking, ...)
  • paid - this boolean field states if cloning the drive from the library is being charged
  • favorite - this boolean field states if this drive is among the most popular library drives

These fields with special meaning could still be changed and deleted (even created if missing) just like every other metadata field. Their content don’t change server/drive’s behavior nor any one of them is required.

Examples

Add meta to a drive:

To add meta to the following drive:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

one has to use update call:

PUT /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Response is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Update server meta, by removing one key and adding another:

Suppose a server is updated to have the following definition:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key1": "value1",
        "meta_key2": "value2"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0e94a85a-d195-488e-b25d-ba6980fe21e4",
    "vnc_password": "updated_password"
}

In order to remove meta_key1, it is just skipped in the meta definition. Keeping meta_key2 with its value is achieved by redefining it, and new key meta_key3 is added by defining it:

PUT /api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0e94a85a-d195-488e-b25d-ba6980fe21e4",
    "vnc_password": "updated_password"
}

The final result is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0e94a85a-d195-488e-b25d-ba6980fe21e4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0e94a85a-d195-488e-b25d-ba6980fe21e4",
    "vnc_password": "updated_password"
}

Availability Grouping and Avoid

Resources requested by user are usually allocated to maximize performance. However this can lead to a situation, where user’s servers or drives share the same compute or storage host. This may be undesirable if the user attempts to build, a redundant setup, as in the unlikely event of hardware failure, servers sharing the same faild compute host will crash at the same time, and drives sharing the same failed storage host will become unavailable at the same time.

To improve the robustness of redundant setups, it is possible to hint the system, which resources are preferred to be on separated physical hosts. This is achieved through the Avoid functionality for starting servers, and for creating/cloning drives.

To check the grouping of running servers on compute hosts, or the grouping of drives on storage hosts, one can use the corresponding availaility_groups API calls.

Checking Availability Groups for Drives and Servers

The availability_groups call returns which resources are grouped on the same physical host.

Server availability groups

GET /servers/availability_groups/
statuscode 200:no error

Returns which running servers share same physical computes host. Returns an array containing arrays. Each inner array holds the UUIDs of servers which reside on same physical host. Non-running servers are not in the array as they are on any host.

GET /servers/availability_groups/{uuid}/
statuscode 200:no error

Queries which other servers share same physical host with the given one. Returns an array holding server UUIDs. The response includes also the UUID of the queried server. If the queried server is not running, the array will be empty.

Drives availability groups

GET /drives/availability_groups/
statuscode 200:no error

Returns which drives share same physical storage host. Returns an array containing arrays. Each inner array holds the UUIDs of drives which reside on same physical host.

GET /drives/availability_groups/{uuid}/
statuscode 200:no error

Queries which other drives share same physical storage host with the given one. Returns an array holding drives UUIDs. The response includes also the UUID of the queried drive.

Examples

Example request - servers availability:

GET /2.0/servers/availability_groups/ HTTP/1.1

Example response - servers availability:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
 [
    "313e73a4-592f-48cf-81c4-a6c079d005a5",
    "e035a488-8587-4a15-ab25-9b7343236bc9"
 ],
 [
    "313e73a4-592f-48cf-81c4-a6c079d005a5",
    "e035a488-8587-4a15-ab25-9b7343236bc9"
 ]
]

Example request - single-server availability:

GET /2.0/servers/availability_groups/313e73a4-592f-48cf-81c4-a6c079d005a5/ HTTP/1.1

Example response - single-server availability:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
 "313e73a4-592f-48cf-81c4-a6c079d005a5",
 "e035a488-8587-4a15-ab25-9b7343236bc9"
]

General Notes on Avoid Functionality

Avoid functionality is best effort. This means that requests containing avoid will succeed even if the avoid can not be satisfied and the requested resource ends in the same availability group as an avoid resource.

The order of the avoid argument UUIDs also specifies the order of preference to avoid. This means that avoid requests are satisfied from left to right, and if it is not possible to satisfy the full avoid list, only part of the aoid list will be satisfied and it will consist of UUIDs from the left part of the list. For example if there are only three hosts which can satisfy a request, and there are three avoid resources on these hosts, the newly request resource, will end up on the same host as the avoid resource which appears last in the list.

Avoid functionality may incur performance penalty. Specifying avoid for drives cloning and servers cloning, as it also clones attached drives, usually slows down significantly the clone operation, as the drive data has to be moved over the network between storage hosts.

Starting Servers in a Different Availability Group (Start Avoid)

POST /servers/{uuid}/action/?do=start&avoid={<server1_uuid>,<server2_uuid>,...}
statuscode 202:Action accepted, execution is proceeding.

Starts a server with specific UUID attempting to run it on a different physical infrastructure host from the other servers specified in the avoid argument which is a single server UUID or a comma-separated list of server UUIDs. This way the server specified by uuid may be run in a distinct availability group from the other listed servers.

Note that it might not always be possible to run a server in a different availability group, therefore the order of the avoid list also signifies the priority of avoiding other servers.

Example request:

POST /2.0/servers/2767d839-3a9d-4bd5-983b-676d1307438f/action/?do=start&avoid=bb1d5184-ebcc-4f33-867e-db654eb2d17e,dc3dd6d4-9b2d-44e6-bc40-e927950e8b77 HTTP/1.1

Creating Drives in a Different Availability Group (Create/Clone Avoid)

POST /drives/{uuid}/action/?do=clone&avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 202:Action accepted, execution is proceeding.
POST /drives/?avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 201:object created
POST /servers/{server_uuid}/action/?do=clone&avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 202:Action accepted, execution is proceeding.

It is possible to hint the system which drives are preferred to be on separate physical storage hosts. Avoid can be specified on all drive creation operations: create, clone drive, and clone server. The value of the avoid GET parameter may contain a single or a comma-separated list of drive or server UUIDs. If a server uuid is in the avoid parameter, this is interpreted as avoiding all the drives attached to the server.

Note that it might not always be create a drive in a different availability group, therefore the order of the avoid list also signifies the priority of avoiding other drives. Since it is not possible to specify the order of drives attached to a server, if a drive from a server needs to be avoided with high priority, it may be specified in addition to the server UUID. For example avoid={important_to_avoid_drive_uuid},{server_uuid_to_which_drive_is_attached}.

Recipe for Creating a Redundant Server Backed by Separate Infrastructure

The best way to create a clone of server that does not share hardware with the original is to clone the origin server with avoiding itself, and to start the clone with avoiding the origing:

POST /2.0/servers/2767d839-3a9d-4bd5-983b-676d1307438f/action/?do=clone&avoid=2767d839-3a9d-4bd5-983b-676d1307438f HTTP/1.1

If the created server uuid is bb1d5184-ebcc-4f33-867e-db654eb2d17e:

POST /2.0/servers/bb1d5184-ebcc-4f33-867e-db654eb2d17e/action/?do=start&avoid=2767d839-3a9d-4bd5-983b-676d1307438f HTTP/1.1

Subscriptions

Statuses

Every subscription has a status associated with it:

  • active: A subscription that is currently being used, either because the current time is between its start or end date or because it was the subscription for depletable resources (traffic) that is currently being used.
  • inactive: A subscription that is not currently being used, either because its not active yet or because there is another depletable resource (traffic) subscription being used.
  • expired: A subscription that has either expired or that has been depleted.

Listing

GET /subscriptions/

Gets the list of subscriptions of the user.

param status:filters only subscriptions in that status. Can be one of active , inactive, expired, all, notexpired. Default is all.
param resource:a list (comma separated) of resources. One or more of: dssd, cpu, mem, tx, ip, vlan.
statuscode 200:no error

Example request:

GET /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 10
    },
    "objects": [
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [
                "/api/2.0/subscriptions/119166/"
            ],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2014-02-20T11:12:34.930946+00:00",
            "id": "7272",
            "period": "345 days, 0:00:00",
            "price": "0E-20",
            "remaining": "1",
            "resource": "vlan",
            "resource_uri": "/api/2.0/subscriptions/7272/",
            "start_time": "2013-03-12T11:12:34.930946+00:00",
            "status": "expired",
            "subscribed_object": "96537817-f4b6-496b-a861-e74192d3ccb0",
            "uuid": "509f8e27-1e64-49bb-aa5a-baec074b0210"
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [
                "/api/2.0/subscriptions/119167/"
            ],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2014-02-20T11:12:41.837474+00:00",
            "id": "7273",
            "period": "345 days, 0:00:00",
            "price": "0E-20",
            "remaining": "1",
            "resource": "ip",
            "resource_uri": "/api/2.0/subscriptions/7273/",
            "start_time": "2013-03-12T11:12:41.837474+00:00",
            "status": "expired",
            "subscribed_object": "185.12.6.183",
            "uuid": "c2423c1a-8768-462c-bdc3-4ca09c1e650b"
        },
        {
            "amount": "17179869184",
            "auto_renew": true,
            "descendants": [
                "/api/2.0/subscriptions/119175/"
            ],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2014-02-20T14:04:14.142181+00:00",
            "id": "3985",
            "period": "365 days, 0:00:00",
            "price": "0E-20",
            "remaining": "17179869184",
            "resource": "mem",
            "resource_uri": "/api/2.0/subscriptions/3985/",
            "start_time": "2013-02-20T14:04:14.142181+00:00",
            "status": "expired",
            "subscribed_object": null,
            "uuid": "9bb117d3-4bc5-4e2d-a907-b20abd48eaf9"
        },
        {
            "amount": "8000",
            "auto_renew": true,
            "descendants": [
                "/api/2.0/subscriptions/119176/"
            ],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2014-02-20T14:04:29.040258+00:00",
            "id": "3986",
            "period": "365 days, 0:00:00",
            "price": "0E-20",
            "remaining": "8000",
            "resource": "cpu",
            "resource_uri": "/api/2.0/subscriptions/3986/",
            "start_time": "2013-02-20T14:04:29.040258+00:00",
            "status": "expired",
            "subscribed_object": null,
            "uuid": "a265c47f-1a00-4095-acfc-2193622bfbd8"
        },
        {
            "amount": "32212254720",
            "auto_renew": true,
            "descendants": [
                "/api/2.0/subscriptions/119178/"
            ],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2014-02-20T14:04:44.088984+00:00",
            "id": "3987",
            "period": "365 days, 0:00:00",
            "price": "0E-20",
            "remaining": "32212254720",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/3987/",
            "start_time": "2013-02-20T14:04:44.088984+00:00",
            "status": "expired",
            "subscribed_object": null,
            "uuid": "8965ff95-4924-40a9-b923-a58615149732"
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2015-01-31T12:00:00+00:00",
            "id": "119166",
            "period": "345 days, 0:00:00",
            "price": "0E-20",
            "remaining": "1",
            "resource": "vlan",
            "resource_uri": "/api/2.0/subscriptions/119166/",
            "start_time": "2014-02-20T12:00:00+00:00",
            "status": "active",
            "subscribed_object": "96537817-f4b6-496b-a861-e74192d3ccb0",
            "uuid": "7576cd51-8e72-4386-bd46-9c5a4a240397"
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2015-01-31T12:00:00+00:00",
            "id": "119167",
            "period": "345 days, 0:00:00",
            "price": "0E-20",
            "remaining": "1",
            "resource": "ip",
            "resource_uri": "/api/2.0/subscriptions/119167/",
            "start_time": "2014-02-20T12:00:00+00:00",
            "status": "active",
            "subscribed_object": "185.12.6.183",
            "uuid": "1f582b4a-d7b0-4ea5-bc2a-1a31bcc6dd07"
        },
        {
            "amount": "8000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2015-02-21T12:00:00+00:00",
            "id": "119176",
            "period": "366 days, 0:00:00",
            "price": "0E-20",
            "remaining": "8000",
            "resource": "cpu",
            "resource_uri": "/api/2.0/subscriptions/119176/",
            "start_time": "2014-02-20T12:00:00+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "a7c78f63-79f0-4a0b-bf31-d2cb31735c70"
        },
        {
            "amount": "32212254720",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2015-02-21T12:00:00+00:00",
            "id": "119178",
            "period": "366 days, 0:00:00",
            "price": "0E-20",
            "remaining": "32212254720",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/119178/",
            "start_time": "2014-02-20T12:00:00+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "7966a12d-cb45-41a1-bd15-ab7aa16518e1"
        },
        {
            "amount": "17179869184",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "end_time": "2015-02-21T12:00:00+00:00",
            "id": "119175",
            "period": "366 days, 0:00:00",
            "price": "0E-20",
            "remaining": "17179869184",
            "resource": "mem",
            "resource_uri": "/api/2.0/subscriptions/119175/",
            "start_time": "2014-02-20T12:00:00+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "818e6bc0-2f4f-4458-983d-91a5acb2e623"
        }
    ],
    "price": "0E-20"
}

Subscription duration

There are three parameters that determine the subscription’s duration. All times are in UTC. Not all combinations are valid:

  • start_time: In ISO 8601 format. Defaults to the current time.
  • end_time: In ISO 8601 format.
  • period: Free form text describing the period. Ex: ‘2 months 1 week’.
Inputs Result
start_time end_time period  
True True True Error: Ambiguous.
True True False Between start_time and end_time.
True False True Period from start_time.
True False False Error: Not specific enough.
False True True Period until end_time.
False True False From now until end_time.
False False True Period from now.
False False False Error: Not specific enough.

Creating

POST /subscriptions/
Status Codes:
  • 201 – object created

Creates a new subscription. There is a limit of 500 subscriptions that can be purchased in one request.

The resource can be a license or one of: dssd (hdd is an alias for this, but is being deprecated), cpu, mem, tx, ip, vlan.

When buying tx, the time parameters are ignored.

Trying to purchase a subscription for IP or VLAN with an amount bigger than one will generate several subscriptions of that type.

Subscription times are rounded to noon UTC, using the following rules:

  • End time is always rounded to the next noon.

  • Start time is rounded to the maximum between the current time an the previous noon. This means that subscriptions bought for now do start now, but subscriptions for the future start at the previous noon.

    Warning

    Subscriptions are mostly immutable for the customer. The only parameter that can be changed is the auto renew.

Example request:

POST /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 30000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "30000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": "0",
            "discount_percent": "0",
            "end_time": "2013-04-22T12:00:00+00:00",
            "id": "28",
            "period": "31 days, 1:31:53.888650",
            "price": "0.000003839842975139617919921875",
            "remaining": "30000",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/28/",
            "start_time": "2013-03-22T10:28:06.111350+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "f622f364-bccf-4a36-a1ce-632a81640ad4"
        }
    ],
    "price": "0.000003839842975139617919921875"
}

Extending

POST /subscriptions/{id}/action/?do=extend
Status Codes:
  • 200 – no error

Extends the subscription. An extended subscription is actually just another subscription that is linked to the original If a period or and end_time are specified in the request,they are used. If neither are specified, the creation length of the subscription is used.

A caveat to this is that a subscription created initially with an end_time, the exact interval is used. Subscriptions that are created with a period have the period parsed again in the context of the new start_time. An example would be a subscription created on the 1st of February with a period of ‘1 month’ will be extended for 31 days, but one that was created with an end date of 1st of March will be extended for 28 days.

If the specified subscription has actually been extended, it traverses and extends the last subscription in the chain.

Autorenewing

POST /subscriptions/{id}/action/?do=auto_renew

Toggles the autorenew flag of the subscription. Optionally, the value can be specified in the request.

Status Codes:
  • 200 – no error

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "post"
    ],
    "allowed_list_http_methods": [
        "get",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "amount": {
            "blank": false,
            "default": 1,
            "help_text": "Subscription amount",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "auto_renew": {
            "blank": false,
            "default": true,
            "help_text": "States if the subscription will auto renew on expire",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "descendants": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscriptions that have been extended from the current one",
            "nullable": true,
            "readonly": true,
            "type": "related",
            "unique": false
        },
        "discount_amount": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Amount of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "discount_percent": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Percent of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "end_time": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "End time of subscription",
            "nullable": true,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Duration of the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "price": {
            "blank": false,
            "default": 0,
            "help_text": "Subscription price",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "remaining": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Amount remaining",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Name of resource associated with the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "start_time": {
            "blank": false,
            "default": "2014-06-05T09:53:46.713863+00:00",
            "help_text": "Start time of subscription",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "status": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Status of the subscription",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "subscribed_object": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscribed object - the target of this subscription, if applicable",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": true
        }
    },
    "filtering": {
        "subscribed_object": [
            "exact"
        ]
    }
}

Grouped subscriptions

GET /groupedsubscriptions/

Returns only the first subscriptions from a chain of extended subscriptions. The extensions are listed in the ‘descendants’ attribute and the end_time is that of the last subscription in the chain.

Status Codes:
  • 200 – no error

Calculator

POST /subscriptioncalculator/

Returns the price of the subscriptions POSTed in the same format as the normal subscriptions.

Status Codes:
  • 200 – no error

Example request:

POST /api/2.0/subscriptioncalculator/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 10000000000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "10000000000",
            "discount_amount": "0",
            "discount_percent": "0",
            "end_time": "2014-07-05T12:00:00+00:00",
            "period": "30 days, 2:06:15.033246",
            "price": "1.303851604461669921875",
            "resource": "dssd",
            "start_time": "2014-06-05T09:53:44.966754+00:00"
        }
    ],
    "price": "1.303851604461669921875"
}

Similarly, the price of extending a subscription can be calculated.

Example request:

POST /api/2.0/subscriptioncalculator/7272/action/?do=extend HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "amount": "1",
    "discount_amount": "11.50000000000000000000000000",
    "discount_percent": "0.1000000000",
    "end_time": "2016-01-11T12:00:00+00:00",
    "period": "345 days, 0:00:00",
    "price": "103.5000000000000000000000000",
    "resource": "vlan",
    "start_time": "2015-01-31T12:00:00+00:00"
}

Accounts

Note

See RFC 2616 for more details on HTTP methods semantics

General

The accounts API supports the following actions

Create account

POST /accounts/action/?do=create
Create an account on the system.
Status Codes:
  • 200 – no error
Parameters:
  • email – The email of the account to be created

Login/Logout

POST /accounts/action/?do=login

Login to the system using cookie auth

Status Codes:
  • 200 – no error
  • 401 – unauthorized

Example request:

POST /accounts/action/?do=login HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{
'username':'123@asd.com',
'password':'parola'

}
Response:
Empty
POST /accounts/action/?do=logout

Logout from the system when using cookie auth

Status Codes:
  • 200 – no error
Example request:
POST /accounts/action/?do=logout HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{}
Response:
Empty
POST /accounts/action/?do=check_login

Check if you are logged in the system

Status Codes:
  • 200 – no error

Example request:

POST /accounts/action/?do=check_login HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{}
Response:
Empty

Audit logs

Note

See RFC 2616 for more details on HTTP methods semantics

General

Audit logs are used to track changes made on your resources, either by you or by other parties, like CloudSigma staff or people that have permission to access you resources.

Querying is done as follows:

GET /logs/
Status Codes:
  • 200 – no error
 
GET /api/2.0/logs/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 3193934
    },
    "objects": [
        {
            "action": "delete",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:29.378194+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "stop",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:26.864672+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "stop_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:24.811553+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "boot",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:48.789732+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "start_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:47.897876+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}

Actions

Actions give information about the operation that created the log. They go in a few categories.

  • General actions - related to most resource types like servers, drives and snapshots:
    • create: During resource creation
    • update: During resource update
    • delete: During resource deletion
    • change_owner: The ownership of the resource has changed. Currently only CloudSigma staff can change ownership of a resource.
    • clone_src: Resource is used as a cloning source
    • clone_dst: Resource is a cloning destination - the newly cloned drive.
  • Drive specific actions - these only relate to drives:
    • move: Drive is moved to another physical storage. Only staff members can move drives.
    • convert_to_library: Drive is converted to a library drive. Only staff members can convert drives.
    • converted_from_library: Drive is converted to a regular drive from a library drive. Only staff members can convert drives.
    • init_upload: Drive upload is initialized.
  • Server specific actions - these only relate to servers:
    • start_send: An attempt to start a server
    • boot: The result of a start operation.
    • stop_send: An attempt to stop a server.
    • stop: The result of a stop operation
    • open_vnc: Open VNC channel to a server
    • close_vnc: Close VNC channel to a server
    • shutdown_ACPI_send: An ACPI shutdown request is send to the server.
    • heal: Server got healed, because its recorded state did not match the physical infrastructure. For example, a server is marked as unavailable, but it is actually running fine.

Errors

If the field success is marked as False, that means that an error occurred during the operation. The error details are saved in the following fields:

  • error_type - States the type of the error
  • error_point - Points to cause of the error and is mainly used for validation errors
  • error_message - Human readable message associated with the error

Example

The following example will show all the logged information during a server’s lifecycle.

First we create a server:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "test_server",
            "vnc_password": "testserver"
        }
    ]
}

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/4002da8d-94d7-4093-ab7a-a78d976a9efc/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc",
            "vnc_password": "testserver"
        }
    ]
}

Upon completion you will see the following log at the top of the audit log list:

GET /api/2.0/logs/?limit=1 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193929
    },
    "objects": [
        {
            "action": "create",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "{\"name\": \"test_server\", \"tags\": [], \"mem\": 536870912, \"smp\": 1, \"cpu\": 1000, \"vnc_password\": \"testserver\"}",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:29.833850+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}
  • action states that we wanted to create a server
  • details state the parameters of the create call
  • actor states the user which executed the operation
  • success is true, so the operation completed successfully.
  • uuid matches the server’s uuid

Then we start the server:

POST /api/2.0/servers/4002da8d-94d7-4093-ab7a-a78d976a9efc/action/?do=start HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "start",
    "result": "success",
    "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
}

We check the logs again. We see that the action is start_send and success is true:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193930
    },
    "objects": [
        {
            "action": "start_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:47.897876+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}

If the server is fully booted and operational, its status will change to running. If it failed to boot for some reason, the error_type, error_point and error_message fields will explain why that happened. In this particular case, we had a successful start, so the audit log looks like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193931
    },
    "objects": [
        {
            "action": "boot",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:48.789732+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}
The pattern is the same when stopping a server:
  • an audit log with action stop_send is saved, representing the status of the request to stop a server.
  • If that succeeded i.e. the request to stop a server is successfully send, you can expect a log with action stop, representing the status of the stop operation i.e. the server actually stopped.

Note

If you stop a server from inside, only a log entry with stop action will be added. This way, you can figure out if the server got stopped from the API or not:

  • If there are 2 logs stop_send and stop, it is stopped via an API request
  • If only stop is present ( no stop_send ), it means that the server is stopped by other means (stopped from inside, crashed, etc).

Schema

GET /logs/schema/
GET /api/2.0/logs/schema/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "action": {
            "default": null,
            "help_text": "Name of the executed action",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "actor": {
            "default": null,
            "help_text": "User who executed action.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "category": {
            "default": null,
            "help_text": "Category the action belongs to.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "details": {
            "default": null,
            "help_text": "Details about the executed action.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_message": {
            "default": null,
            "help_text": "Error message, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_point": {
            "default": null,
            "help_text": "The field that caused the error, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_type": {
            "default": null,
            "help_text": "Type of error, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "success": {
            "default": true,
            "help_text": "Whether the action was successful.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "timestamp": {
            "default": null,
            "help_text": "Time when entry was added.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "The uuid of resource the action is executed on. Can be empty, meaning no resource is referenced.",
            "readonly": false,
            "required": false,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Profile

Allowed HTTP methods

Method Description
GET get the profile object
PUT update the profile object

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /profile/

Gets the user profile. Note that profile is a single object so the API does not return a list.

statuscode 200:no error

Example request:

GET /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "address": "1 Main str.",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "NONE",
    "company": "",
    "country": "BG",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "en-au",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2014-06-05 08:15:39.864947",
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2013-05-28T11:57:01.090639+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "Mr",
    "town": "Sofia",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": "123"
}

Editing

PUT /profile/
statuscode 200:no error

Edits a user profile. (We want to change the company name for example)

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "1 Main str.",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "NONE",
    "company": "Newly Set Company Name",
    "country": "BG",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "en-au",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2014-06-05 08:15:39.864947",
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2013-05-28T11:57:01.090639+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "Mr",
    "town": "Sofia",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": "123"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "address": "1 Main str.",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "NONE",
    "company": "Newly Set Company Name",
    "country": "BG",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "en-au",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2014-06-05 08:15:39.864947",
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2013-05-28T11:57:01.090639+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "Mr",
    "town": "Sofia",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": "123"
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put"
    ],
    "allowed_list_http_methods": [
        "get",
        "put"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "address": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "api_https_only": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "autotopup_amount": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "autotopup_threshold": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "bank_reference": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "clone_naming": {
            "blank": false,
            "default": "NONE",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "company": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "country": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "currency": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "email": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "first_name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "has_autotopup": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "invoicing": {
            "blank": false,
            "default": true,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "key_auth": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "language": {
            "blank": false,
            "default": "EN",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "last_name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "mailing_list": {
            "blank": false,
            "default": true,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "meta": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "nullable": false,
            "readonly": false,
            "type": "dict",
            "unique": false
        },
        "my_notes": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "nickname": {
            "blank": false,
            "default": "",
            "help_text": "User nickname",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "phone": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "postcode": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "reseller": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "signup_time": {
            "blank": false,
            "default": "2014-06-05T09:47:34.474924+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "state": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "tax_name": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "tax_rate": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": true,
            "readonly": true,
            "type": "decimal",
            "unique": false
        },
        "title": {
            "blank": false,
            "default": "",
            "help_text": "User title",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "town": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "vat": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        }
    }
}

Notification contacts

Listing

GET /notification_contacts/

Gets the list of contacts configured for the account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/notification_contacts/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "email": "some_email_1@example.com",
            "main": true,
            "name": "Some Name",
            "phone": "",
            "resource_uri": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "uuid": "e13c4b8c-68c8-4163-bc00-2a43a86e5937"
        }
    ]
}

Creating

POST /notification_contacts/

Creates a new contact.

Status Codes:
  • 201 – object created

Example request:

POST /api/2.0/notification_contacts/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "email": "some_email_2@example.com",
            "name": "Some Name 2",
            "phone": "+1 123 555 1234"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "email": "some_email_2@example.com",
            "main": null,
            "name": "Some Name 2",
            "phone": "+11235551234",
            "resource_uri": "/api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/",
            "uuid": "0103f398-9f85-446a-a285-fe63cf9f0f28"
        }
    ]
}

Editing

PUT /notification_contacts/{uuid}/

Edits a notification contact. Note that changing the main user’s email is not recommended, as if the account email changes, so will the main contact.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "email": "some_email_2@example.com",
    "name": "Some New Name"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "email": "some_email_2@example.com",
    "main": null,
    "name": "Some New Name",
    "phone": "+11235551234",
    "pk": "0103f398-9f85-446a-a285-fe63cf9f0f28",
    "resource_uri": "/api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/",
    "uuid": "0103f398-9f85-446a-a285-fe63cf9f0f28"
}

Deleting

DELETE /notification_contacts/{uuid}/

Delete a notification contact. Note that you cannot delete the main contact.

Status Codes:
  • 204 – no errors

Example request:

DELETE /api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Notification preferences

Listing

GET /notification_preferences/

Gets the list of contacts configured for the account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/notification_preferences/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 22
    },
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_withheld",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_failed",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_failure",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "out_of_money_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "stop_servers",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_success",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "out_of_money_very_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "drives_delete_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_very_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "new_account",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "reset_password",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "drives_delete",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "random_upgrade",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_cancelled",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire_very_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_approved",
            "value": true
        }
    ]
}

Updating

PUT /notification_preferences/

Updates the specified preferences. Only the ones in the request are modified.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/notification_preferences/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
    "medium": "email",
    "type": "trial_expire",
    "value": true
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": true
        }
    ]
}

Multiple objects can be specified in the request.

Example request:

PUT /api/2.0/notification_preferences/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

[
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "trial_expire",
        "value": false
    },
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "payment_withheld",
        "value": true
    },
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "payment_failed",
        "value": false
    }
]

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_withheld",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_failed",
            "value": false
        }
    ]
}

Billing

Balance

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /balance/

Get the balance and currency of the current account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/balance/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "balance": "469291.07488238102453490453",
    "currency": "USD"
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "Amount of money in account",
            "readonly": true,
            "required": true,
            "type": "decimal"
        },
        "currency": {
            "default": "No default provided.",
            "help_text": "Currency of the account",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Pricing

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /pricing/

Gets the pricing information that are applicable to the cloud. Subscription prices use a burst level of 0.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/pricing/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "current": {
        "cpu": 15,
        "dssd": 1,
        "ip": 1,
        "mem": 11,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_lwa_00135": 1,
        "msft_p71_01031": 1,
        "msft_p73_04837": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00009": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "ssd": 1,
        "tx": 20,
        "vlan": 1,
        "zadara": 1
    },
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 392
    },
    "next": {
        "cpu": 15,
        "dssd": 1,
        "ip": 1,
        "mem": 11,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_lwa_00135": 1,
        "msft_p71_01031": 1,
        "msft_p73_04837": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00009": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "ssd": 1,
        "tx": 20,
        "vlan": 1,
        "zadara": 1
    },
    "objects": [
        {
            "currency": "CHF",
            "id": "308",
            "level": 0,
            "multiplier": 2783138807808000,
            "price": "0.12600000000000000000",
            "resource": "ssd",
            "unit": "GB/month"
        },
        {
            "currency": "EUR",
            "id": "309",
            "level": 0,
            "multiplier": 2783138807808000,
            "price": "0.10080000000000000000",
            "resource": "ssd",
            "unit": "GB/month"
        },
        {
            "currency": "GBP",
            "id": "310",
            "level": 0,
            "multiplier": 2783138807808000,
            "price": "0.08680000000000000000",
            "resource": "ssd",
            "unit": "GB/month"
        },
        {
            "currency": "USD",
            "id": "311",
            "level": 0,
            "multiplier": 2783138807808000,
            "price": "0.14000000000000000000",
            "resource": "ssd",
            "unit": "GB/month"
        },
        {
            "currency": "GBP",
            "id": "680",
            "level": 1,
            "multiplier": 2592000,
            "price": "3.10000000000000000000",
            "resource": "ip",
            "unit": "IP"
        }
    ]
}

Burst levels

The current and future burst levels are provided in objects at the root of the response. The burst levels are calculated every 5 minutes based on the usage of the cloud and are applied 5 minutes later (when the next burst levels are calculated)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "current": {
        "cpu": 15,
        "dssd": 1,
        "ip": 1,
        "mem": 11,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_lwa_00135": 1,
        "msft_p71_01031": 1,
        "msft_p73_04837": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00009": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "ssd": 1,
        "tx": 20,
        "vlan": 1,
        "zadara": 1
    },
    "next": {
        "cpu": 15,
        "dssd": 1,
        "ip": 1,
        "mem": 11,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_lwa_00135": 1,
        "msft_p71_01031": 1,
        "msft_p73_04837": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00009": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "ssd": 1,
        "tx": 20,
        "vlan": 1,
        "zadara": 1
    }
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "currency": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The currency of the price",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "level": {
            "blank": false,
            "default": 0,
            "help_text": "The burst level the price applies to",
            "nullable": false,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "multiplier": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The multiplier applied to get the price of one unit per second, from the unit of the price",
            "nullable": false,
            "readonly": true,
            "type": "integer",
            "unique": false
        },
        "price": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Price",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "resource": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The resource the price applies to",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "unit": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The unit of the price",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        }
    },
    "filtering": {
        "level": 1
    }
}

Discounts

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /discount/

Get discount information.

statuscode 200:no error

Example request:

GET /api/2.0/discount/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "period": "3 months",
            "value": "0.0300000000"
        },
        {
            "period": "6 months",
            "value": "0.1000000000"
        },
        {
            "period": "1 year",
            "value": "0.2500000000"
        },
        {
            "period": "2 years",
            "value": "0.3500000000"
        },
        {
            "period": "3 years",
            "value": "0.4500000000"
        }
    ]
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The minimum period for this discount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "value": {
            "blank": false,
            "default": 0,
            "help_text": "The value of the discount",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        }
    }
}

Transaction list

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /ledger/

Get the transactions for the account.

statuscode 200:no error

Example request:

GET /api/2.0/ledger/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 98203
    },
    "objects": [
        {
            "amount": "0.00014583333333333333",
            "billing_cycle": 105157,
            "end": "469291.07488238102453490453",
            "human_interval": "5 minutes",
            "id": "39509304",
            "initial": "469291.07502821435786823786",
            "interval": 300,
            "poll_time": "2014-06-05T09:06:06.713945+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 09:06",
            "resource_amount": "4831838208",
            "time": "2014-06-05T09:08:47.992023+00:00"
        },
        {
            "amount": "0.00908310000000000000",
            "billing_cycle": 105150,
            "end": "469291.07502821435786823786",
            "human_interval": "2 minutes",
            "id": "39506824",
            "initial": "469291.08411131435786823786",
            "interval": 137,
            "poll_time": "2014-06-05T08:31:06.610957+00:00",
            "reason": "Burst: 12.00 GHz of cpu for 2 minutes at 2014-06-05 08:31",
            "resource_amount": "12000",
            "time": "2014-06-05T08:33:48.047354+00:00"
        },
        {
            "amount": "0.00255733333333333333",
            "billing_cycle": 105150,
            "end": "469291.08411131435786823786",
            "human_interval": "2 minutes",
            "id": "39506823",
            "initial": "469291.08666864769120157119",
            "interval": 137,
            "poll_time": "2014-06-05T08:31:06.610957+00:00",
            "reason": "Burst: 4.00 GB of mem for 2 minutes at 2014-06-05 08:31",
            "resource_amount": "4294967296",
            "time": "2014-06-05T08:33:48.036326+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105148,
            "end": "469291.08666864769120157119",
            "human_interval": "5 minutes",
            "id": "39506114",
            "initial": "469291.08681399491342379341",
            "interval": 299,
            "poll_time": "2014-06-05T08:21:06.603517+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 08:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T08:23:50.433096+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469291.08681399491342379341",
            "human_interval": null,
            "id": "39505412",
            "initial": "469235.63681399491342095124",
            "interval": null,
            "poll_time": "2014-06-05T08:16:04.495196+00:00",
            "reason": "Payment through card - 9fddd858-ec89-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T08:16:04.495183+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "469235.63681399491342095124",
            "human_interval": null,
            "id": "39505411",
            "initial": "469158.40681399491341697220",
            "interval": null,
            "poll_time": "2014-06-05T08:15:58.552271+00:00",
            "reason": "Payment through card - 9c37a0bc-ec89-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T08:15:58.552247+00:00"
        },
        {
            "amount": "0.00888420000000000000",
            "billing_cycle": 105138,
            "end": "469158.40681399491341697220",
            "human_interval": "2 minutes",
            "id": "39502556",
            "initial": "469158.41569819491341697220",
            "interval": 134,
            "poll_time": "2014-06-05T07:31:06.597276+00:00",
            "reason": "Burst: 12.00 GHz of cpu for 2 minutes at 2014-06-05 07:31",
            "resource_amount": "12000",
            "time": "2014-06-05T07:33:51.033990+00:00"
        },
        {
            "amount": "0.00250133333333333333",
            "billing_cycle": 105138,
            "end": "469158.41569819491341697220",
            "human_interval": "2 minutes",
            "id": "39502555",
            "initial": "469158.41819952824675030553",
            "interval": 134,
            "poll_time": "2014-06-05T07:31:06.597276+00:00",
            "reason": "Burst: 4.00 GB of mem for 2 minutes at 2014-06-05 07:31",
            "resource_amount": "4294967296",
            "time": "2014-06-05T07:33:51.022223+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105136,
            "end": "469158.41819952824675030553",
            "human_interval": "5 minutes",
            "id": "39501851",
            "initial": "469158.41834487546897252775",
            "interval": 299,
            "poll_time": "2014-06-05T07:21:06.607872+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 07:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T07:23:49.590257+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469158.41834487546897252775",
            "human_interval": null,
            "id": "39501157",
            "initial": "469102.96834487546896968558",
            "interval": null,
            "poll_time": "2014-06-05T07:16:04.926285+00:00",
            "reason": "Payment through card - 3fe9a3bc-ec81-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T07:16:04.926273+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "469102.96834487546896968558",
            "human_interval": null,
            "id": "39501156",
            "initial": "469025.73834487546896570654",
            "interval": null,
            "poll_time": "2014-06-05T07:16:01.585853+00:00",
            "reason": "Payment through card - 3dca136e-ec81-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T07:16:01.585840+00:00"
        },
        {
            "amount": "0.00633993750000000000",
            "billing_cycle": 105126,
            "end": "469025.73834487546896570654",
            "human_interval": "2 minutes",
            "id": "39498298",
            "initial": "469025.74468481296896570654",
            "interval": 135,
            "poll_time": "2014-06-05T06:31:06.554201+00:00",
            "reason": "Burst: 8.50 GHz of cpu for 2 minutes at 2014-06-05 06:31",
            "resource_amount": "8500",
            "time": "2014-06-05T06:33:52.255963+00:00"
        },
        {
            "amount": "0.00031500000000000000",
            "billing_cycle": 105126,
            "end": "469025.74468481296896570654",
            "human_interval": "2 minutes",
            "id": "39498297",
            "initial": "469025.74499981296896570654",
            "interval": 135,
            "poll_time": "2014-06-05T06:31:06.554201+00:00",
            "reason": "Burst: 0.50 GB of mem for 2 minutes at 2014-06-05 06:31",
            "resource_amount": "536870912",
            "time": "2014-06-05T06:33:52.244645+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105124,
            "end": "469025.74499981296896570654",
            "human_interval": "5 minutes",
            "id": "39497582",
            "initial": "469025.74514516019118792876",
            "interval": 299,
            "poll_time": "2014-06-05T06:21:06.570020+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 06:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T06:23:51.102193+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469025.74514516019118792876",
            "human_interval": null,
            "id": "39496879",
            "initial": "468970.29514516019118508659",
            "interval": null,
            "poll_time": "2014-06-05T06:16:03.979389+00:00",
            "reason": "Payment through card - dc2f7084-ec78-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T06:16:03.979376+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "468970.29514516019118508659",
            "human_interval": null,
            "id": "39496878",
            "initial": "468893.06514516019118110755",
            "interval": null,
            "poll_time": "2014-06-05T06:15:58.310868+00:00",
            "reason": "Payment through card - d88fbc54-ec78-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T06:15:58.310852+00:00"
        },
        {
            "amount": "0.00536987500000000000",
            "billing_cycle": 105114,
            "end": "468893.06514516019118110755",
            "human_interval": "2 minutes",
            "id": "39494022",
            "initial": "468893.07051503519118110755",
            "interval": 133,
            "poll_time": "2014-06-05T05:31:06.501327+00:00",
            "reason": "Burst: 7.50 GHz of cpu for 2 minutes at 2014-06-05 05:31",
            "resource_amount": "7500",
            "time": "2014-06-05T05:33:52.682096+00:00"
        },
        {
            "amount": "0.00014583333333333333",
            "billing_cycle": 105112,
            "end": "468893.07051503519118110755",
            "human_interval": "5 minutes",
            "id": "39493319",
            "initial": "468893.07066086852451444088",
            "interval": 300,
            "poll_time": "2014-06-05T05:21:06.511910+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 05:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T05:23:50.866953+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "468893.07066086852451444088",
            "human_interval": null,
            "id": "39492621",
            "initial": "468837.62066086852451159871",
            "interval": null,
            "poll_time": "2014-06-05T05:15:59.277046+00:00",
            "reason": "Payment through card - 78fc2118-ec70-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T05:15:59.277034+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "468837.62066086852451159871",
            "human_interval": null,
            "id": "39492620",
            "initial": "468760.39066086852450761967",
            "interval": null,
            "poll_time": "2014-06-05T05:15:55.898020+00:00",
            "reason": "Payment through card - 76a699d4-ec70-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T05:15:55.898007+00:00"
        }
    ]
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "amount": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of the operation, positive for debits, negative for credits",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "billing_cycle": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Billing cycle that generated this charge",
            "nullable": true,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "end": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of money after the operation",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "human_interval": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Human readable interval of bill entry",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "initial": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of money before the operation",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "interval": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Interval of bill entry",
            "nullable": true,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "poll_time": {
            "blank": false,
            "default": "2014-06-05T09:41:58.809494+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "reason": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Description of the operation",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_amount": {
            "blank": false,
            "default": 1,
            "help_text": "Resource amount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "time": {
            "blank": false,
            "default": "2014-06-05T09:41:58.809480+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        }
    },
    "filtering": {
        "billing_cycle": 1,
        "time": 1
    },
    "ordering": [
        "time"
    ]
}

Discounts

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /discount/

Get discount information.

statuscode 200:no error

Example request:

GET /api/2.0/discount/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "period": "3 months",
            "value": "0.0300000000"
        },
        {
            "period": "6 months",
            "value": "0.1000000000"
        },
        {
            "period": "1 year",
            "value": "0.2500000000"
        },
        {
            "period": "2 years",
            "value": "0.3500000000"
        },
        {
            "period": "3 years",
            "value": "0.4500000000"
        }
    ]
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The minimum period for this discount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "value": {
            "blank": false,
            "default": 0,
            "help_text": "The value of the discount",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        }
    }
}

Current usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /currentusage/

Get the current usage of the user.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/currentusage/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "balance": {
        "balance": "469291.07488238102453490453",
        "currency": "USD"
    },
    "usage": {
        "cpu": {
            "burst": 0,
            "subscribed": 8000,
            "using": 0
        },
        "dssd": {
            "burst": 0,
            "subscribed": 32212254720,
            "using": 24696061952
        },
        "ip": {
            "burst": 0,
            "subscribed": 1,
            "using": 1
        },
        "mem": {
            "burst": 0,
            "subscribed": 17179869184,
            "using": 0
        },
        "msft_7jq_00341": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_7nq_00302": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_p73_04837_core": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_tfa_00523": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "sms": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "tx": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "vlan": {
            "burst": 0,
            "subscribed": 1,
            "using": 1
        },
        "zadara": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        }
    }
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        },
        "usage": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Licenses list

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /licenses/

Get the licenses available on the cloud. The type of the license can be one of:

Status Codes:
  • 200 – no error
  • install - These licenses are billed per installation, regardless of whether it is attached to a running server or not.
  • instance - These licenses are billed per running instance of a server. A license attached to a guest that’s stopped is not billed.
  • stub - These licenses are billed per a metric specified by the customer (i.e. per number of users license)

The user metric field specifies what attribute on the instance of the server is used for determining the number of licenses. For example, “smp” will count one license for each CPU/core in the virtual machine.

Example request:

GET /api/2.0/licenses/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "burstable": false,
            "long_name": "SQL Server Enterprise Edition",
            "name": "msft_7jq_00341",
            "resource_uri": "/api/2.0/licenses/13/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": false,
            "long_name": "SQL Server Standard Edition",
            "name": "msft_7nq_00302",
            "resource_uri": "/api/2.0/licenses/14/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": true,
            "long_name": "Windows Server",
            "name": "msft_p73_04837_core",
            "resource_uri": "/api/2.0/licenses/12/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": false,
            "long_name": "SQL Server Web",
            "name": "msft_tfa_00523",
            "resource_uri": "/api/2.0/licenses/15/",
            "type": "instance",
            "user_metric": "smp"
        }
    ]
}

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "burstable": {
            "blank": false,
            "default": false,
            "help_text": "Whether this resource can be used on burst",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "long_name": {
            "blank": false,
            "default": "",
            "help_text": "A human readable name for the resource.",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "name": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Name that should be used when purchasing",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "type": {
            "blank": false,
            "default": "instance",
            "help_text": "Type of billing",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "user_metric": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The metric that the user is charged for",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        }
    }
}

Current Usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /currentusage/

Gets the current usage of the authenticated user has access.

Parameters:
  • context – another account whose drives should be listed
Status Codes:
  • 200 – no error

Example request:

GET /2.0/currentusage/ HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json
Authorization: Basic dGVzdHVzZXJAY2xvdWRzaWdtYS5jb206dmJudmJu

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "balance": {
        "balance": "9899.16666666666666666667",
        "currency": "CHF"
    },
    "usage": {
        "cpu": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "dssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ip": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "mem": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "vlan": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        }
    }
}

Request schema

None.

Response schema

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        },
        "usage": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        }
    }
}

Asynchronous server

Authentication

In order to use the asynchronous server, you must first authenticate through the API. This will give you a cookie that is valid for 2 minutes and that has to be used when connecting to the server.

statuscode 200:no error

Example request:

POST /2.0/accounts/action/?do=authenticate_asynchronous HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json
Authorization: Basic dGVzdHVzZXJAY2xvdWRzaWdtYS5jb206dmJudmJu

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8
Set-Cookie: async_auth=YTlhZmMwYTctOWYzNi00ZmUzLThlYmUtMGZiOGZlODE0ZmQx|1356012032|f785e3d8083c7666209e54477652de0d057f0791; expires=Thu, 20-Dec-2012 14:02:32 GMT; Max-Age=120; Path=/

{}

Using this cookie will allow you to connect to the server at /2.0/websocket

Information

The websocket server sends frames every time one of the following changes:

The frame is a JSON object that contains the following fields:
  • resource_type: A text field that describes the type of resource covered by the notification.
  • resource_uri: The URI of the resource that has changed.

The JSON object might contain a ‘object’ key, that will contain the full blown resource referenced by the notification, JSON encoded.

Indices and tables