Loading...
REST API

General

Login

Example Request:

POST https://cloud.ravellosystems.com/api/v1/login

Example Response:

{
    "activated": true,
    "email": "ravello@ravello.com",
    "enabled": true,
    "id": 8,
    "invitationTime": 1398755048359,
    "name": "Ravello admin",
    "organization": 8,
    "roles": ["ADMIN", "USER"],
    "surname": "Ravello admin",
    "uuid": "Admin_b74f4d59-c743-4792-8da5-9bc858921eb6"
}
 Show full example

Login with username and password (basic authorization) to access the Ravello API.

HTTP Request

POST /login

Parameters

Authorization header required.

Response

Status Code Description
200 OK The logged-in user details
401 Unauthorized When the password/username is not correct

Logout

Example Request:

POST https://cloud.ravellosystems.com/api/v1/logout

Logs out of the system.

HTTP Request

POST /logout

Parameters

No parameters required.

Response

Status Code Description
204 No Content Successfully logged out.

Applications

Get Applications List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications

Example Response:

[
    {
        "creationTime": 1398774913233,
        "design": {},
        "designDiffersFromDeployment": false,
        "id": 360451,
        "name": "App1",
        "owner": "Ravello admin Ravello admin",
        "published": false,
        "version": 2
    },
    {
        "creationTime": 1398774926540,
        "deployment": {
            "expirationTime": 1398782139110,
            "publishOptimization": "COST_OPTIMIZED",
            "publishStartTime": 1398774938893,
            "totalActiveVms": 2,
            "cloudRegion": {
                "name": "us-central-1",
                "displayName": "US Central 1",
                "deprecated": false
            }
        },
        "design": {},
        "designDiffersFromDeployment": false,
        "id": 360452,
        "name": "App2",
        "owner": "Ravello admin Ravello admin",
        "published": true,
        "version": 3
    },
    {
        "creationTime": 1398774942067,
        "deployment": {
            "expirationTime": 1398782149537,
            "publishOptimization": "PERFORMANCE_OPTIMIZED",
            "publishStartTime": 1398774949307,
            "totalActiveVms": 1,
            "cloudRegion": {
                "name": "us-east-1",
                "displayName": "US East 1",
                "deprecated": false
            }
        },
        "design": {},
        "designDiffersFromDeployment": false,
        "id": 360453,
        "name": "App3",
        "owner": "Ravello admin Ravello admin",
        "published": true,
        "version": 3
    }
]
 Show full example

Returns a list of all the application under the authenticated user’s organization. The returned list doesn’t contain the full application, but only a general description of their properties. Use GET /applications/:id to get the full data for a specific application.

HTTP Request

GET /applications

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of application descriptions

Get Application

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/34045955

Example Response:

{
    "creationTime": 1398774926540,
    "deployment": {
        "expirationTime": 1400000243099,
        "expirationType": "AUTO_STOPPED",
        "cloudRegion": {
            "name": "us-central-1",
            "displayName": "US Central 1",
            "deprecated": false
        },
        "network": {
            "dnsService": {
                "host": [
                    {
                        "ip": "10.0.0.3",
                        "name": "db"
                    }
                ],
                "id": 1205275897850899156
            },
            "routerLegs": [
                {
                    "id": 3061093093996677683,
                    "ip": "10.0.0.2",
                    "routerRef": 5013998812030713664,
                    "subnetRef": 8558389469711571435
                }
            ],
            "routers": [
                {
                    "id": 5013998812030713664,
                    "isExternal": true
                }
            ],
            "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 8956729313820737361,
                        "ip": "10.0.0.1",
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 8558389469711571435,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1626952983,
                        288349138
                    ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "publishOptimization": "COST_OPTIMIZED",
        "publishStartTime": 1398774938893,
        "totalActiveVms": 2,
        "vms": [
            {
                "applicationId": 360452,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1398774938402,
                "description": "ubuntu-12-4-cloudinit",
                "externalFqdn": "ubuntu124cloudinit-app2-sok8h3ka.srv.agineo.com",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "virtio",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 588944518,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.2-20130325.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "id": 2067532896,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "ubuntu-12-4-cloudinit",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "generatedMac": "2c:c2:60:2f:e5:3d",
                            "index": 0,
                            "pciSlot": 0,
                            "useAutomaticMac": true
                        },
                        "id": 2032038216,
                        "ipConfig": {
                            "autoIpConfig": {
                                "allocatedIp": "10.0.0.4"
                            },
                            "fqdn": "ubuntu124cloudinit-app2-sok8h3ka.srv.agineo.com",
                            "hasPublicIp": false,
                            "id": 288349138,
                            "publicIp": "54.227.153.214"
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "state": "STARTING",
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1355550885,
                        "ipConfigLuid": 288349138,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 360452,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1398774938425,
                "description": "A database for the guided tour sample application. Running MySQL on top of Centos 6.3. To SSH into the machine use ravello/ravelloCloud.",
                "externalFqdn": "databasesampleapplic-app2-lee1sngd.srv.agineo.com",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 994109308,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.1-20121218.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "db"
                ],
                "id": 288734069,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Database - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:76:de:0b",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 1147754854,
                        "ipConfig": {
                            "autoIpConfig": {
                                "allocatedIp": "10.0.0.3"
                            },
                            "fqdn": "databasesampleapplic-app2-lee1sngd.srv.agineo.com",
                            "hasPublicIp": false,
                            "id": 1626952983,
                            "publicIp": "54.227.153.214"
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "state": "STARTING",
                "suppliedServices": [
                    {
                        "external": false,
                        "id": 1403950578,
                        "name": "sql",
                        "portRange": "3306",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 706133406,
                        "ipConfigLuid": 1626952983,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            }
        ]
    },
    "design": {
        "layout": {
            "vmLayoutItem": [
                {
                    "location": {
                        "x": 570,
                        "y": 140
                    },
                    "vmId": 2067532896
                },
                {
                    "location": {
                        "x": 385,
                        "y": 255
                    },
                    "vmId": 288734069
                }
            ]
        },
        "network": {
            "dnsService": {
                "id": 1205275897850899156
            },
            "routerLegs": [
                {
                    "id": 3061093093996677683,
                    "routerRef": 5013998812030713664,
                    "subnetRef": 8558389469711571435
                }
            ],
            "routers": [
                {
                    "id": 5013998812030713664,
                    "isExternal": true
                }
            ],
            "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 8956729313820737361,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 8558389469711571435,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1626952983,
                        288349138
                    ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "vms": [
            {
                "applicationId": 360452,
                "baseVmId": 10,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1398774928627,
                "description": "ubuntu-12-4-cloudinit",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "virtio",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 588944518,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.2-20130325.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "id": 2067532896,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "ubuntu-12-4-cloudinit",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "generatedMac": "2c:c2:60:2f:e5:3d",
                            "index": 0,
                            "pciSlot": 0,
                            "useAutomaticMac": true
                        },
                        "id": 2032038216,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 288349138
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1355550885,
                        "ipConfigLuid": 288349138,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 360452,
                "baseVmId": 9,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1398774929904,
                "description": "A database for the guided tour sample application. Running MySQL on top of Centos 6.3. To SSH into the machine use ravello/ravelloCloud.",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 994109308,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.1-20121218.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "db"
                ],
                "id": 288734069,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Database - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:76:de:0b",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 1147754854,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 1626952983
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": false,
                        "id": 1403950578,
                        "name": "sql",
                        "portRange": "3306",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 706133406,
                        "ipConfigLuid": 1626952983,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            }
        ]
    },
    "designDiffersFromDeployment": false,
    "id": 360452,
    "name": "App2",
    "owner": "Ravello admin Ravello admin",
    "published": true,
    "version": 3
}
 Show full example

Returns the full application data, including the application properties, list of VMs, the application network, and so on. The application has two aspects: the design and the deployment. The design describes the saved application and all the user’s changes. The deployment describes the application on the cloud, exactly as it was when it was last published. You can see the difference between the design and deployment by comparing, for example, two VMs with the same ID. There could be more changes in the network, network filter and other properties.

Note: If the application has not been published, there is not deployment information.

There are additional ways to execute this call:

GET /applications/:id;design - returns the application with only the design aspect

GET /applications/:id;deployment - returns the application with only the deployment aspect

GET /applications/:id;properties - returns the application with only the properties aspect

HTTP Request

GET /applications/:id [;deployment or ;design or ;properties]

Parameters

Parameter Required Description
id yes The ID of the application

Response

Status Code Description
200 OK Full application
404 Not Found When the specified ID does not exist

Create Application

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/
{
    "name": "MyApp",
    "description" : "My Application Description",
    "baseBlueprintId": 51904660
}
 Show full example

Example Response:

{
    "baseBlueprintId": 51904660,
    "blueprintName": "App1-bp",
    "creationTime": 1399993327915,
    "description": "My Application Description",
    "design": {
        "layout": {
            "vmLayoutItem": [
                {
                    "location": {
                        "x": 625,
                        "y": 285
                    },
                    "vmId": 1156753549
                },
                {
                    "location": {
                        "x": 510,
                        "y": 135
                    },
                    "vmId": 1899827343
                },
                {
                    "location": {
                        "x": 905,
                        "y": 225
                    },
                    "vmId": 2101584772
                }
            ]
        },
        "network": {
            "dnsService": {
                "id": 3307456326639140504
            },
            "routerLegs": [
                {
                    "id": 5405319594118609461,
                    "routerRef": 5538406040859516592,
                    "subnetRef": 6662652102148285103
                }
            ],
            "routers": [
                {
                    "id": 5538406040859516592,
                    "isExternal": true
                }
            ],
            "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 77828843280412355,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 6662652102148285103,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1867310527,
                        749734423,
                        1908615374
                    ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "vms": [
            {
                "applicationId": 884741,
                "baseVmId": 8,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327946,
                "description": "A web server for the guided installation sample application. Running Apache and Wordpress on top of Centos 6.2. To SSH into the machine use ravello/ravelloCloud.",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 1498506386,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "storefile_0e44148f-c04d-427f-a86e-d2525dce2d8c",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "wordpress"
                ],
                "id": 2101584772,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 4
                },
                "name": "Webserver - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:82:5f:6f",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 2062058632,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 749734423
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                    {
                        "external": false,
                        "id": 1231790023,
                        "name": "sql",
                        "protocol": "TCP",
                        "targetHostName": "db"
                    }
                ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1031747050,
                        "ipConfigLuid": 749734423,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 224986770,
                        "ipConfigLuid": 749734423,
                        "name": "http",
                        "portRange": "80",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 884741,
                "baseVmId": 10,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327935,
                "description": "ubuntu-12-4-cloudinit",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "virtio",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 383171394,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.2-20130325.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "id": 1899827343,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "ubuntu-12-4-cloudinit",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "generatedMac": "2c:c2:60:1c:e8:b4",
                            "index": 0,
                            "pciSlot": 0,
                            "useAutomaticMac": true
                        },
                        "id": 1620276705,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 1867310527
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 351471684,
                        "ipConfigLuid": 1867310527,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 884741,
                "baseVmId": 9,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327949,
                "description": "A database for the guided tour sample application. Running MySQL on top of Centos 6.3. To SSH into the machine use ravello/ravelloCloud.",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 565307244,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.1-20121218.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "db"
                ],
                "id": 1156753549,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Database - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:76:de:0b",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 1316202969,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": true,
                            "id": 1908615374
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": false,
                        "id": 534242613,
                        "name": "sql",
                        "portRange": "3306",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 1743854188,
                        "ipConfigLuid": 1908615374,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            }
        ]
    },
    "designDiffersFromDeployment": false,
    "id": 884741,
    "name": "MyApp",
    "owner": "Ravello admin Ravello admin",
    "published": false,
    "version": 0
}
 Show full example

Creates a new application, using the given template from the user. It is possible to create empty applications, meant for adding more VMs later, using PUT /applications/:id. Alternatively, users can create a new application from blueprint, by specifying blueprintId in the request. See more information about building an application in the Building an Application section.

HTTP Request

POST /applications

Parameters

Parameter Required Description
name yes The name of the new application
description no A description of the new application
baseBlueprintId no Specify this parameter to create a new application from an existing blueprint.
design yes The wrapping object for all the design properties of the application, including the virtual machines, network and more.
vms no A list of the virtual machines in the application design. See Building an Application to read more about application VMs.
network no The application designed network - includes the subnet, routers, and more. Generally the user does not need to construct this object as it being built automatically after every change. See Building an Application to read more about the application network.
networkFilter no Contains rules about who can access the application and how. See Building an Application to read more about the network filter.
vmOrderGroups no Contains application groups to sequence the starting/stopping of VMs. See Building an Application to read more about this feature.

Response

Status Code Description
201 Created The full application created
400 Bad Request When there is an error with the creation parameters or when the application name is not unique.
404 Not Found When the given blueprint id (if given) does not exist.

Update Application

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/applications/34045955
{
    "baseBlueprintId": 51904660,
    "blueprintName": "App1-bp",
    "creationTime": 1399993327915,
    "description": "My Application Description",
    "design": {
        "layout": {
            "vmLayoutItem": [
            {
                "location": {
                    "x": 625,
                    "y": 285
                },
                "vmId": 1156753549
            },
            {
                "location": {
                    "x": 510,
                    "y": 135
                },
                "vmId": 1899827343
            },
            {
                "location": {
                    "x": 905,
                    "y": 225
                },
                "vmId": 2101584772
            }
            ]
        },
        "network": {
            "dnsService": {
                "id": 3307456326639140504
            },
            "routerLegs": [
            {
                "id": 5405319594118609461,
                "routerRef": 5538406040859516592,
                "subnetRef": 6662652102148285103
            }
            ],
                "routers": [
                {
                    "id": 5538406040859516592,
                    "isExternal": true
                }
            ],
                "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 77828843280412355,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 6662652102148285103,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1867310527,
                    749734423,
                    1908615374
                        ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "vms": [
        {
            "applicationId": 884741,
            "baseVmId": 8,
            "bootOrder": [
                "CDROM",
            "DISK"
                ],
            "configurationManagement": {},
            "creationTime": 1399993327946,
            "description": "A web server for the guided installation sample application. Running Apache and Wordpress on top of Centos 6.2. To SSH into the machine use ravello/ravelloCloud.",
            "hardDrives": [
            {
                "boot": true,
                "controller": "pvscsi",
                "controllerIndex": 0,
                "controllerPciSlot": 0,
                "id": 1498506386,
                "imageFetchMode": "LAZY",
                "index": 0,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "name": "storefile_0e44148f-c04d-427f-a86e-d2525dce2d8c",
                "peripheral": false,
                "size": {
                    "unit": "GB",
                    "value": 15
                },
                "type": "DISK"
            }
            ],
                "hostnames": [
                    "wordpress"
                    ],
                "id": 2101584772,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 4
                },
                "name": "Webserver - Sample Application",
                "networkConnections": [
                {
                    "accessPort": true,
                    "device": {
                        "deviceType": "e1000",
                        "index": 0,
                        "mac": "00:0c:29:82:5f:6f",
                        "pciSlot": 0,
                        "useAutomaticMac": false
                    },
                    "id": 2062058632,
                    "ipConfig": {
                        "autoIpConfig": {},
                        "hasPublicIp": false,
                        "id": 749734423
                    }
                }
            ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                {
                    "external": false,
                    "id": 1231790023,
                    "name": "sql",
                    "protocol": "TCP",
                    "targetHostName": "db"
                }
            ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                {
                    "external": true,
                    "id": 1031747050,
                    "ipConfigLuid": 749734423,
                    "name": "ssh",
                    "portRange": "22",
                    "protocol": "TCP"
                },
                {
                    "external": true,
                    "id": 224986770,
                    "ipConfigLuid": 749734423,
                    "name": "http",
                    "portRange": "80",
                    "protocol": "TCP"
                }
            ],
                "supportsCloudInit": true,
                "useCdn": false
        },
        {
            "applicationId": 884741,
            "baseVmId": 10,
            "bootOrder": [
                "CDROM",
            "DISK"
                ],
            "configurationManagement": {},
            "creationTime": 1399993327935,
            "description": "ubuntu-12-4-cloudinit",
            "hardDrives": [
            {
                "boot": true,
                "controller": "virtio",
                "controllerIndex": 0,
                "controllerPciSlot": 0,
                "id": 383171394,
                "imageFetchMode": "LAZY",
                "index": 0,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "name": "ravello-ubuntu-12.04.2-20130325.qcow2",
                "peripheral": false,
                "size": {
                    "unit": "GB",
                    "value": 15
                },
                "type": "DISK"
            }
            ],
                "id": 1899827343,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "ubuntu-12-4-cloudinit",
                "networkConnections": [
                {
                    "accessPort": true,
                    "device": {
                        "deviceType": "e1000",
                        "generatedMac": "2c:c2:60:1c:e8:b4",
                        "index": 0,
                        "pciSlot": 0,
                        "useAutomaticMac": true
                    },
                    "id": 1620276705,
                    "ipConfig": {
                        "autoIpConfig": {},
                        "hasPublicIp": false,
                        "id": 1867310527
                    }
                }
            ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                {
                    "external": true,
                    "id": 351471684,
                    "ipConfigLuid": 1867310527,
                    "name": "ssh",
                    "portRange": "22",
                    "protocol": "TCP"
                }
            ],
                "supportsCloudInit": true,
                "useCdn": false
        },
        {
            "applicationId": 884741,
            "baseVmId": 9,
            "bootOrder": [
                "CDROM",
            "DISK"
                ],
            "configurationManagement": {},
            "creationTime": 1399993327949,
            "description": "A database for the guided tour sample application. Running MySQL on top of Centos 6.3. To SSH into the machine use ravello/ravelloCloud.",
            "hardDrives": [
            {
                "boot": true,
                "controller": "pvscsi",
                "controllerIndex": 0,
                "controllerPciSlot": 0,
                "id": 565307244,
                "imageFetchMode": "LAZY",
                "index": 0,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "name": "ravello-ubuntu-12.04.1-20121218.qcow2",
                "peripheral": false,
                "size": {
                    "unit": "GB",
                    "value": 15
                },
                "type": "DISK"
            }
            ],
                "hostnames": [
                    "db"
                    ],
                "id": 1156753549,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Database - Sample Application",
                "networkConnections": [
                {
                    "accessPort": true,
                    "device": {
                        "deviceType": "e1000",
                        "index": 0,
                        "mac": "00:0c:29:76:de:0b",
                        "pciSlot": 0,
                        "useAutomaticMac": false
                    },
                    "id": 1316202969,
                    "ipConfig": {
                        "autoIpConfig": {},
                        "hasPublicIp": true,
                        "id": 1908615374
                    }
                }
            ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                {
                    "external": false,
                    "id": 534242613,
                    "name": "sql",
                    "portRange": "3306",
                    "protocol": "TCP"
                },
                {
                    "external": true,
                    "id": 1743854188,
                    "ipConfigLuid": 1908615374,
                    "name": "ssh",
                    "portRange": "22",
                    "protocol": "TCP"
                }
            ],
                "supportsCloudInit": true,
                "useCdn": false
        }
        ]
    },
    "designDiffersFromDeployment": false,
    "id": 884741,
    "name": "MyUpdatedApp",
    "owner": "Ravello admin Ravello admin",
    "published": false,
    "version": 0
}
 Show full example

Example Response:

{
    "baseBlueprintId": 51904660,
    "blueprintName": "App1-bp",
    "creationTime": 1399993327915,
    "description": "My Application Description",
    "design": {
        "layout": {
            "vmLayoutItem": [
                {
                    "location": {
                        "x": 625,
                        "y": 285
                    },
                    "vmId": 1156753549
                },
                {
                    "location": {
                        "x": 510,
                        "y": 135
                    },
                    "vmId": 1899827343
                },
                {
                    "location": {
                        "x": 905,
                        "y": 225
                    },
                    "vmId": 2101584772
                }
            ]
        },
        "network": {
            "dnsService": {
                "id": 4269069704291448482
            },
            "routerLegs": [
                {
                    "id": 7853394588421513209,
                    "routerRef": 6204855169555196361,
                    "subnetRef": 3712616482019033939
                }
            ],
            "routers": [
                {
                    "id": 6204855169555196361,
                    "isExternal": true
                }
            ],
            "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 1223229602370321120,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 3712616482019033939,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1867310527,
                        749734423,
                        1908615374
                    ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "vms": [
            {
                "applicationId": 884741,
                "baseVmId": 8,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327946,
                "description": "A web server for the guided installation sample application. Running Apache and Wordpress on top of Centos 6.2. To SSH into the machine use ravello/ravelloCloud.",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 1498506386,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "storefile_0e44148f-c04d-427f-a86e-d2525dce2d8c",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "wordpress"
                ],
                "id": 2101584772,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 4
                },
                "name": "Webserver - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:82:5f:6f",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 2062058632,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 749734423
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                    {
                        "external": false,
                        "id": 1231790023,
                        "name": "sql",
                        "protocol": "TCP",
                        "targetHostName": "db"
                    }
                ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1031747050,
                        "ipConfigLuid": 749734423,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 224986770,
                        "ipConfigLuid": 749734423,
                        "name": "http",
                        "portRange": "80",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 884741,
                "baseVmId": 9,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327949,
                "description": "A database for the guided tour sample application. Running MySQL on top of Centos 6.3. To SSH into the machine use ravello/ravelloCloud.",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "pvscsi",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 565307244,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.1-20121218.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "db"
                ],
                "id": 1156753549,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Database - Sample Application",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "index": 0,
                            "mac": "00:0c:29:76:de:0b",
                            "pciSlot": 0,
                            "useAutomaticMac": false
                        },
                        "id": 1316202969,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": true,
                            "id": 1908615374
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": false,
                        "id": 534242613,
                        "name": "sql",
                        "portRange": "3306",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 1743854188,
                        "ipConfigLuid": 1908615374,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            },
            {
                "applicationId": 884741,
                "baseVmId": 10,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1399993327935,
                "description": "ubuntu-12-4-cloudinit",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "virtio",
                        "controllerIndex": 0,
                        "controllerPciSlot": 0,
                        "id": 383171394,
                        "imageFetchMode": "LAZY",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ravello-ubuntu-12.04.2-20130325.qcow2",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 15
                        },
                        "type": "DISK"
                    }
                ],
                "id": 1899827343,
                "internal": false,
                "keypairId": 2,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "ubuntu-12-4-cloudinit",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "e1000",
                            "generatedMac": "2c:c2:60:1c:e8:b4",
                            "index": 0,
                            "pciSlot": 0,
                            "useAutomaticMac": true
                        },
                        "id": 1620276705,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": false,
                            "id": 1867310527
                        }
                    }
                ],
                "numCpus": 1,
                "os": "default",
                "platform": "default",
                "rcu": 1.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 351471684,
                        "ipConfigLuid": 1867310527,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "useCdn": false
            }
        ]
    },
    "designDiffersFromDeployment": false,
    "id": 884741,
    "name": "MyUpdatedApp",
    "owner": "Ravello admin Ravello admin",
    "published": false,
    "version": 1
}
 Show full example

Updates the application data and properties. The update here is full update, meaning the application will be replaced (elegantly) according to the given application object, i.e., one cannot handle a request as a partial application, because that would simply delete the missing part from the actual application. Example: if the method gets an empty list of VMs, it will delete all the VMs from the application.

HTTP Request

PUT /applications/:id

Parameters

Parameter Required Description
id yes The ID of the application.
name yes The name of the application.
description no A description of the application.
blueprintId no Specify this parameter to create a new application from an existing blueprint.
design yes The wrapping object for all the design properties of the application, including the virtual machines, network and more.
vms no A list of the virtual machines in the application design. See Building an Application to read more about application VMs.
network no The application designed network - includes the subnet, routers, and more. Generally the user does not need to construct this object as it being built automatically after every change. See Building an Application to read more about the application network.
networkFilter no Contains rules about who can access the application and how. See Building an application to read more about the network filter.
vmOrderGroups no Contains application groups to sequence the starting/stopping of VMs. See Building an Application to read more about this feature.

Response

Status Code Description
200 OK Full application
400 Bad Request When there is some error with the request parameters.
404 Not Found When the specified ID does not exist.

Delete Application

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/applications/34045955

Deletes the application and releases all the resources associated with it. The application cannot be restored, the deletion is permanent - all data on the machines is lost.

HTTP Request

DELETE /applications/:id

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
204 No Content The application was deleted successfully.
404 Not Found When the specified ID does not exist.

Publish Application

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/34045955/publish
{
    "preferredRegion": "us-central-1",
    "optimizationLevel": "PERFORMANCE_OPTIMIZED",
    "startAllVms": "true"
}
 Show full example

Publish the design to the cloud.

HTTP Request

POST /applications/:id/publish

Parameters

Parameter Required Description
id yes The ID of the application.
optimizationLevel yes Specify this property to control the optimization of the application deployment. Must be: COST_OPTIMIZED or PERFORMANCE_OPTIMIZED.
preferredRegion * The preferred region on the cloud in which the application will be deployed.
startAllVms no Set this property to False to publish VMs without starting them. The default value is True.

Response

Status Code Description
202 Accepted The server is processing the request.
400 Bad Request When the application is already published, Invalid design, or invalid preferred region.
403 Forbidden When the quota or time-lease have exceeded
404 Not Found When the specified ID does not exist.

Execute Application Action

Example Request - Starting all VMs in the application:

POST https://cloud.ravellosystems.com/api/v1/applications/34045955/start

Example Request - Publish updates for the application, do not start VMs:

https://cloud.ravellosystems.com/api/v1/applications/34045955/publishUpdates?startAllDraftVms=false

Example Response:

{
    "completedSuccessfuly": "true",
    "operationMessages": [{
        "vmId": "2",
        "errorLevel": "INFO/ERROR/WARN",
        "message": "Vm is in the middle of another action"
    } ]
}
 Show full example

Performs an action on a published application.

HTTP Request

POST /applications/:id/:action

Possible Actions

Action Description
» publishUpdates Updates the cloud according to the current application data.
When the application is changed and saved, its cloud status remains the same as it was at the last publish. For the changes to take effect, you must publish the updates. The correct flow is to first update the application using PUT /applications/:id, and then use publishUpdates to update the application on the cloud.
» start Starts all the application VMs. VMs that are already started arel not affected.
» stop Stops all the application VMs. Stops only the published VMs (does not affect the stopped ones).
» restart Restarts all the application VMs.
» resetDisks Resets each of the VM disks to its most recent applicable state: its state in the library, its state when it was last stopped, or its state when it was saved to the library.

Parameters

Parameter Required Description
id yes The ID of the application.
action yes Refer to one of the possible actions. Must be: start, stop, restart, or publishUpdates.
startAllDraftVms no This is a query parameter. When set to False, newly added draft VMs will not start after publish updates action. The default value is true. This parameter is relevant only for the publishUpdates action. See usage example.

Response

Status Code Description
202 Accepted An operation result summary
Note: This call will return 202 even if no VM was actually handled, since you can view the failed VMs in the operation messages list.
400 Bad Request Depending on the action:

Start: When the application is already started or not published.

Stop: When the application is not published.

Restart: When the application is not published.

Publish Changes: When the application is not published or has validation errors.
403 Forbidden When the quota or time-lease have been exceeded.
404 Not Found When the specified ID does not exist.

Get VMs List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/34045955/vms

Returns a list of all the VMs in the application. These are full VM objects, including all the properties and components of the VMs.

There are additional ways to execute this call:

GET /applications/:id;design/vms - returns the application design VMs list.

GET /applications/:id;deployment/vms - returns the deployed VMs list on the cloud.

HTTP Request

GET /applications/:id/vms [;deployment or ;design] *

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
200 OK The list of VMs.
404 Not Found When the specified ID does not exist.

Get VM

Example Request with request body:

GET https://cloud.ravellosystems.com/api/v1/applications/34045955/vms/12

Example Response:

{
    "id": 12,
    "name": "example-vm",
    "description": "ubuntu-14.04.1-20150302",
    "creationTime": 1459690696154,
    "memorySize": {
        "value": 4,
        "unit": "GB"
    },
    "numCpus": 1,
    "platform": "default",
    "os": "default",
    "rcu": 1,
    "supportsCloudInit": true,
    "requiresKeypair": true,
    "useCdn": false,
    "privateCloudImage": false,
    "applicationId": 34045955,
    "legacyMode": false,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "keypairId": 98305,
    "keypairName": "a",
    "baseVmId": 32777,
    "suppliedServices": [
        {
            "id": 165805422513624,
            "name": "ssh",
            "portRange": "22",
            "protocol": "TCP",
            "external": true,
            "ipConfigLuid": 4518047032598382,
            "useLuidForIpConfig": true
        }
    ],
    "networkConnections": [
        {
            "id": 1036588782647566,
            "device": {
                "useAutomaticMac": true,
                "index": 0,
                "deviceType": "e1000",
                "generatedMac": "2c:c2:60:22:6e:19"
            },
            "ipConfig": {
                "id": 4518047032598382,
                "fqdn": "my-fqdn.provider.com",
                "autoIpConfig": {
                    "allocatedIp": "10.0.0.3"
                },
                "hasPublicIp": false,
                "externalAccessState": "ALWAYS_PORT_FORWARDING",
                "needElasticIp": false
            },
            "name": "eth0",
            "accessPort": true,
            "vlanTag": "1",
            "mirror": false
        }
    ],
    "hardDrives": [
        {
            "id": 7580139133615168,
            "name": "ubuntu-14.04.1-20150302.qcow2",
            "boot": true,
            "size": {
                "value": 15,
                "unit": "GB"
            },
            "index": 0,
            "type": "DISK",
            "imageFetchMode": "LAZY",
            "controller": "virtio",
            "controllerIndex": 0,
            "loadingStatus": "DONE",
            "loadingPercentage": 100
        }
    ],
    "configurationManagement": {
        "configNetworkUsingCloudInit": false
    },
    "bootOrder": [
        "CDROM",
        "DISK"
    ],
    "powerOffOnStopTimeOut": true,
    "configNetworkUsingCloudInit": false,
    "requiresHvm": false
}
 Show full example

Returns a specific VM in the application.

There are additional ways to execute this call:

GET /applications/:appId;design/vms/:vmId - returns the designed VM.

GET /applications/:appId;deployment/vms/:vmId - returns the deployed VM on the cloud.

HTTP Request

GET /applications/:appId/vms/:vmId [;deployment or ;design] *

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the virtual machine.

Response

Status Code Description
200 OK The requested VM.
404 Not Found When the specified ID does not exist.

Update VM

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/applications/34045955/vms/12
{
    "id": 12,
    "name": "my-vm",
    "description": "ubuntu-14.04.1-20150302-B",
    "applicationId": 34045955,
    "bootOrder": [
        "CDROM",
        "DISK"
    ],
    "configNetworkUsingCloudInit": false,
    "configurationManagement": {
        "configNetworkUsingCloudInit": false
    },
    "baseVmId": 32777,
    "creationTime": 1459690696154,
    "hardDrives": [
        {
            "boot": true,
            "controller": "virtio",
            "controllerIndex": 0,
            "id": 7580139133615168,
            "imageFetchMode": "LAZY",
            "index": 0,
            "loadingPercentage": 100,
            "loadingStatus": "DONE",
            "name": "ubuntu-14.04.1-20150302.qcow2",
            "size": {
                "unit": "GB",
                "value": 15
            },
            "type": "DISK"
        }
    ],
    "keypairId": 98305,
    "keypairName": "a",
    "legacyMode": false,
    "loadingPercentage": 100,
    "loadingStatus": "DONE",
    "memorySize": {
        "unit": "GB",
        "value": 2
    },
    "networkConnections": [
        {
            "accessPort": true,
            "device": {
                "deviceType": "e1000",
                "generatedMac": "2c:c2:60:22:6e:19",
                "index": 0,
                "useAutomaticMac": true
            },
            "id": 1036588782647566,
            "ipConfig": {
                "autoIpConfig": {
                    "allocatedIp": "10.0.0.3"
                },
                "externalAccessState": "ALWAYS_PORT_FORWARDING",
                "fqdn": "my-fqdn.provider.com",
                "hasPublicIp": false,
                "id": 4518047032598382,
                "needElasticIp": false
            },
            "mirror": false,
            "name": "eth0",
            "vlanTag": "1"
        }
    ],
    "numCpus": 1,
    "os": "default",
    "platform": "default",
    "powerOffOnStopTimeOut": true,
    "privateCloudImage": false,
    "rcu": 1,
    "requiresHvm": false,
    "requiresKeypair": true,
    "suppliedServices": [
        {
            "external": true,
            "id": 165805422513624,
            "ipConfigLuid": 4518047032598382,
            "name": "ssh",
            "portRange": "22",
            "protocol": "TCP",
            "useLuidForIpConfig": true
        }
    ],
    "supportsCloudInit": true,
    "useCdn": false
}
 Show full example

Example Response:

{
    "id": 34045955,
    "name": "my-app",
    "owner": "Ravello",
    "ownerDetails": {
        "userId": 32774,
        "name": "Admin user",
        "deleted": false
    },
    "creationTime": 1459690689637,
    "design": {
        "vms": [
            {
                "id": 12,
                "name": "my-vm",
                "description": "ubuntu-14.04.1-20150302-B",
                "creationTime": 1459690696154,
                "memorySize": {
                    "value": 2,
                    "unit": "GB"
                },
                "numCpus": 1,
                "platform": "default",
                "os": "default",
                "rcu": 1,
                "supportsCloudInit": true,
                "requiresKeypair": true,
                "useCdn": false,
                "privateCloudImage": false,
                "applicationId": 229379,
                "legacyMode": false,
                "loadingStatus": "DONE",
                "loadingPercentage": 100,
                "keypairId": 98305,
                "keypairName": "a",
                "baseVmId": 32777,
                "suppliedServices": [
                    {
                        "id": 165805422513624,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP",
                        "external": true,
                        "ipConfigLuid": 4518047032598382,
                        "useLuidForIpConfig": true
                    }
                ],
                "networkConnections": [
                    {
                        "id": 1036588782647566,
                        "device": {
                            "useAutomaticMac": true,
                            "index": 0,
                            "deviceType": "e1000",
                            "generatedMac": "2c:c2:60:22:6e:19"
                        },
                        "ipConfig": {
                            "id": 4518047032598382,
                            "fqdn": "my-fqdn.provider.com",
                            "autoIpConfig": {
                                "allocatedIp": "10.0.0.3"
                            },
                            "hasPublicIp": false,
                            "externalAccessState": "ALWAYS_PORT_FORWARDING",
                            "needElasticIp": false
                        },
                        "name": "eth0",
                        "accessPort": true,
                        "vlanTag": "1",
                        "mirror": false
                    }
                ],
                "hardDrives": [
                    {
                        "id": 7580139133615168,
                        "name": "ubuntu-14.04.1-20150302.qcow2",
                        "boot": true,
                        "size": {
                            "value": 15,
                            "unit": "GB"
                        },
                        "index": 0,
                        "type": "DISK",
                        "imageFetchMode": "LAZY",
                        "controller": "virtio",
                        "controllerIndex": 0,
                        "loadingStatus": "DONE",
                        "loadingPercentage": 100
                    }
                ],
                "configurationManagement": {
                    "configNetworkUsingCloudInit": false
                },
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "powerOffOnStopTimeOut": true,
                "configNetworkUsingCloudInit": false,
                "requiresHvm": false
            }
        ],
        "network": {
            "subnets": [
                {
                    "id": 2739090506654779400,
                    "dhcp": {
                        "id": 3559757368391090700,
                        "ip": "10.0.0.1",
                        "active": true,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254",
                        "entries": [
                            {
                                "networkConnectionId": 1036588782647566,
                                "ip": "10.0.0.3"
                            }
                        ]
                    },
                    "networkConnectionRefs": [
                        4518047032598382
                    ],
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0"
                }
            ],
            "routers": [
                {
                    "id": 4861939611952490000,
                    "isExternal": true
                }
            ],
            "routerLegs": [
                {
                    "id": 2152953510831812000,
                    "subnetRef": 2739090506654779400,
                    "routerRef": 4861939611952490000,
                    "ip": "10.0.0.2"
                }
            ],
            "dnsService": {
                "entries": [
                    {
                        "name": "myvm",
                        "ip": "10.0.0.3",
                        "index": 1000000,
                        "type": "A"
                    },
                    {
                        "name": "my-fqdn.provider.com",
                        "ip": "10.0.0.3",
                        "index": 1000001,
                        "type": "A"
                    }
                ],
                "id": 926040458644055600
            },
            "dnsLegs": [
                {
                    "id": 0,
                    "subnetRef": 2739090506654779400,
                    "dnsRef": 926040458644055600,
                    "ip": "10.0.0.1"
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false,
            "blockOutgoingTraffic": false
        },
        "layout": {
            "vmLayoutItem": [
                {
                    "location": {
                        "x": 120,
                        "y": 3
                    },
                    "vmId": 6015552827241798
                }
            ]
        },
        "stopVmsByOrder": false
    },
    "designDiffersFromDeployment": false,
    "published": false,
    "version": 4
}
 Show full example

Updates a specific VM in the application.

HTTP Request

PUT /applications/:appId/vms/:vmId

VM Properties

Name Description
name The name of the image.
description The description of the VM.
creationTime The creation time of the VM (when it was first saved).
memorySize The memory size defined for the VM. It’s composed of unit and value. Unit can be one of “GB”,“MB”, “KB”, “BYTE” and the value is long. Example:
"memorySize" : { "unit": "GB", "value": 10 }
numCpus The number of CPUs in the VM.
platform The original virtualization platform, possible values: “DEFAULT”, “V2-ESX”
os The operating system.
supportsCloudInit Set this to true if the VM has cloud-init installed. Currently we support vanilla cloud-init v0.7.5 and up (Ubuntu 14.04 and later, Fedora Cloud images, etc). See here for more details.
userData Cloud-init’s behaviour can be configured using this field. See available formats here.
requiresKeypair Specifies whether or not the system should enforce setting a public key for SSH connectivity.(If false, a pre-configured authentication mechanism is used.)
keypairId When requiresKeypair set to true, set this field to the chosen key pair.
hostnames List of hostnames for the VM.
applicationId The ID of the application that this VM belongs to.
legacyMode Enables legacy mode for higher virtual hardware compatibility. Important: legacy mode is much slower than the default mode. We strongly advise to use it only after a discussion with us.
loadingStatus This field has two different meanings. On a design VM, this holds the loading status of the image that the VM is based on, since one can add a new VM to the design even if it’s not fully loaded yet.

Possible upload values: UPLOADING, PARSING, PENDING, PAUSED, SAVING, DONE, DELETING, DELETED, ERROR_UPLOADING, ERROR, UNKNOWN.

On a published VM, if a snapshot process is running (happens also automatically on stop), this field returns the status of that process.

Possible snapshot values: POST_SNAPSHOTTING, PRE_SNAPSHOTTING, SNAPSHOTTING, DONE.
loadingPercentage When the loading status of the VM is UPLOADING or SNAPSHOTTING, this indicates the percentage of data already uploaded or saved as snapshot.
baseVmId The ID of the library VM that this VM is based on.
biosUuid The BIOS unique identifier used for licensing or checking vendor hardware platform.
cpuIds Supported CPU features exposed to guest VMs.
bootOrder Specifies the boot order for the VM, for example: [‘CDROM’, 'DISK’]
rtc Real Time Clock - Sets the timezone for the VM. This is an object containing a String mode and a long number seconds. The possible modes are ABSOLUTE or RELATIVE and the seconds should set the timezone.

Example:
"rtc" : { "mode": "RELATIVE", "seconds": 7200 }


Default:
{ "mode": "RELATIVE", "seconds": 0 }
displayDevice The display device for this VM. Make sure your VM has the required driver for the selected device. Possible values are: “default”, “vmware-svga”, “VGA” (upper case).
vmOrderGroupId Links the VM with the group for setting VMs start/stop order. See more details under Setting the VM Start/Stop Order section.
stopTimeOut Time to wait for VM to stop successfully, default is 20 minutes.

VM Inner Objects

Name Description
hardDrives List of hard drives used in the VM.
networkConnections List of network interfaces.
suppliedServices List of supplied services. For simplicity, define a single external SSH service.
requiredServices List of required services.

Response

Status Code Description
200 OK The updated VM.
404 Not Found When the specified application ID or VM ID does not exist.

Execute Single VM Action

Example Request - Publish updates for the application, do not start VMs:

POST https://cloud.ravellosystems.com/api/v1/applications/340955/vms/548/stop

Performs an action on a specific VM in a published application.

HTTP Request

POST /applications/:appId/vms/:vmId/:action

Possible Actions

Action Description
» start Starts the VM.
» stop Shuts down the VM gracefully, following the configured timeout. Timeout can be set via the VM stopTimeOut parameter. The default setting is 20 minutes.
» shutdown An operating system that recognizes this signal shuts down gracefully, without timeout.
» poweroff The VM is abruptly powered off, with no consideration for work in progress.
» restart Restart the VM.
» redeploy Shut the VM down and replace it with a new copy. This is a “last resort” option, and it deletes all the data that have been written to the machine after the publish.
» repair Makes an attempt to repair the VM without destroying the data.
» resetDisks Resets each of the VM disks to its most recent applicable state: its state in the library, its state when it was last stopped, or its state when it was saved to the library.

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the virtual machine.
action yes Refer to one of the possible actions. Must be: start, stop, restart, redeploy or repair.

Response

Status Code Description
202 Accepted The server is processing the request.
400 Bad Request When the VM is in the middle of another action (busy).
403 Forbidden When the quota or time-lease is exceeded.
404 Not Found When the specified ID does not exist.

Execute Multiple VMs Action

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/340955/vms/stop

JSON:

{
   "ids": ["id_1", "id_2", "id_N"]
}
 Show full example

XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idsList >
   <ids>ID_1</ids>
   <ids>ID_2</ids>
   ...
   <ids>ID_N</ids>
</idsList>

Performs an action on a list of VMs in a published application.

HTTP Request

POST /applications/:appId/vms/:action

Possible Actions

Action Description
» start Starts the VM.
» stop Stops the VM.
» restart Restart the VM.
» redeploy Shuts down the VM and replaces it with a new copy. This is a “last resort” option, and it deletes all the data that have been written to the machine after the publish.
» repair Makes an attempt to repair the VM without destroying the data.
» shutdown Stops the VM gracefully, no server timeout.
» poweroff Stops the VM immediately, non-graceful way.

Parameters

Parameter Required Description
appId yes The ID of the application.
action yes Refer to one of the possible actions. Must be: start, stop, restart, redeploy and repair.
vmIds yes A list containing the VMs IDs to execute the action on.

Response

Status Code Description
202 Accepted The server is processing the request.
400 Bad Request When the given VMs list is empty, or when one of the VMs is in the middle of another action (busy).
403 Forbidden When the quota or time-lease is exceeded.
404 Not Found When one of the specified IDs does not exist.

Get All Publish Locations

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/34045/publishLocations

Example Response:

[
    {
        "regionName": "us-central-1",
        "regionDisplayName": "US Central 1",
        "deprecated": false
    },
    {
        "regionName": "us-east-1",
        "regionDisplayName": "US East 1",
        "deprecated": false
    },
    {
        "regionName": "Virginia",
        "regionDisplayName": "Virginia",
        "deprecated": true
    }
]
 Show full example

Finds all the possible publish location for the given application, considering the storage and CPU needs. The list is sorted by costs – low to high.

HTTP Request

GET /applications/:id/publishLocations

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
200 OK Sorted list of all the possible publish locations
404 Not Found When the specified ID does not exist.

Set Application Expiration Time

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/3404595/setExpiration
{
    "expirationFromNowSeconds": 7200
}
 Show full example

In order to minimize costs, it is possible to set applications with auto-stop timeout, which determines when the application will be automatically stopped. It is important to ensure that applications are not forgotten alive without any usage. The auto-stop time can be updated to control the scheduling of this feature.

HTTP Request

POST applications/:id/setExpiration

Parameters

Parameter Required Description
id yes The ID of the application.
expirationFromNowSeconds yes The time in seconds (from now) when the application will be stopped. Set it to -1 to mark unlimited time.

Response

Status Code Description
200 OK Returns the application expiration time.
400 Bad Request When the time given is not valid.
404 Not Found When the specified ID does not exist.

Get VM VNC URL

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/3405/vms/2524/vncUrl
GET https://cloud.ravellosystems.com/api/v1/applications/3405/vms/2524/vncUrl?readOnly=true

Returns the URL for connecting to the VM remotely using VNC. Includes the authentication token needed to connect. This is useful to create an independent applet/form to connect remotely to the user’s VMs.

HTTP Request

GET applications/:appId/vms/:vmId/vncUrl

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the VM.
readOnly no This is a query parameter - when set to true the VNC session will be read only.

Response

Status Code Description
200 OK Returns the VNC URL.
404 Not Found When the specified ID does not exist.

Detailed Charges for Application

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/3404595/calcPrice;design
{
    "optimizationLevel" : "PERFORMANCE_OPTIMIZED"
}
 Show full example

Example Request (No body is needed):

POST https://cloud.ravellosystems.com/api/v1/applications/3404595/calcPrice;deployment

Example Response:

{
    "appTier": "ADVANCED",
    "optimizationLevel": "PERFORMANCE_OPTIMIZED",
    "productsSummary": [
        {
            "productCount": 0,
            "productType": "NETWORKING_MB",
            "productUname": "NETWORKING_MB",
            "summaryPrice": 0
        },
        {
            "productCount": 1,
            "productType": "R1",
            "productUname": "R1.ADVANCED.PERFORMANCE_OPTIMIZED",
            "summaryPrice": 0
        },
        {
            "productCount": 15360,
            "productType": "DISKSPACE_MB",
            "productUname": "DISKSPACE_MB",
            "summaryPrice": 0.005178082191780864
        },
        {
            "productCount": 1,
            "productType": "MINIMUM",
            "productUname": "MINIMUM.ADVANCED.PERFORMANCE_OPTIMIZED",
            "summaryPrice": 0.5
        }
    ],
    "totalActiveVms": 1,
    "totalAppCpuCount": 1,
    "totalAppMemoryInGb": 2.0,
    "totalDiskspaceInGb": 15.0,
    "totalIpAddressCount": 0,
    "totalPrice": 0.5051780821917808
}
 Show full example

Returns the detailed charges for the application. The prices are given in USD. For more details about the pricing, refer to Ravello’s pricing explained.

POST /applications/:id;design/calcPrice - returns the pricing according to the application design. All parameters are required.

POST /applications/:id;deployment/calcPrice - returns the pricing according to the deployed VMs list on the cloud, no parameters are needed.

HTTP Request

POST application/:id/calcPrice [;deployment or ;design]

Parameters - only when using the ;design parameter.

Parameter Required Description
id yes The ID of the application.
optimizationLevel yes The level of optimization which affects the price. Possible values: PERFORMANCE_OPTIMIZED, COST_OPTIMIZED

Response

Status Code Description
200 OK Successfully returns the application pricing details.
400 Bad Request When the parameter optimization level is not valid or missing.
404 Not Found When the specified ID does not exist.

Get FQDN String of Deployed VM

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/168/vms/13/fqdn;deployment

Example Response:

{
    "value" :  "automationshelfvmc-webdriverinstance0-fgv4g6jf.dev.agineo.com"
}
 Show full example

Returns the FQDN string of a deployed VM.

HTTP Request

GET applications/:appId/vms/:vmId/fqdn;deployment

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the published VM.

Response

Status Code Description
200 OK The VM FQDN string
404 Not Found When the specified application ID or VM ID does not exist.

Get Cloud State of Deployed VM

Example Request with request body:

GET https://cloud.ravellosystems.com/api/v1/applications/168/vms/13/state;deployment

Returns the state of a deployed VM. Possible values are: PUBLISHING, WAITING_TO_START, STARTING, STARTED, RESTARTING, RESETTING_DISKS, WAITING_TO_STOP, STOPPING, STOPPED, TERMINATING, TERMINATED, ERROR, UNKNOWN, UPDATING, REPAIRING, ERROR_DEPLOY, ERROR_TERMINATE.

HTTP Request

GET applications/:appId/vms/:vmId/state;deployment

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the published VM.

Response

Status Code Description
200 OK The deployed VM state.
404 Not Found When the specified application ID or VM ID does not exist.

Get List of Public IPs of Deployed VM

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/168/vms/13/publicIps;deployment

Example Response:

{
    "ips": [
        "153.92.34.232"
    ]
}
 Show full example

Returns a list of the VM public IPs.

HTTP Request

GET applications/:appId/vms/:vmId/publicIps;deployment

Parameters

Parameter Required Description
appId yes The ID of the application.
vmId yes The ID of the published VM.

Response

Status Code Description
200 OK A list of the VM public IP addresses.
404 Not Found When the specified application ID or VM ID does not exist.

Check If Application is Published or Not

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/168/isPublished

Example Response:

{
    "value": true
}
 Show full example

Returns a boolean value specifying whether the application is published on the cloud.

HTTP Request

GET applications/:appId/isPublished

Parameters

Parameter Required Description
appId yes The ID of the application.

Response

Status Code Description
200 OK A boolean value.
404 Not Found When the specified application ID does not exist.

Add VM to Application (Design)

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/340955/vms
{
    "baseVmId" : 10
}
 Show full example

Adds a new VM to the application. Currently, the only supported option is to add a VM based on an image from the library. The request body should include the field baseVmId with the desired image ID (see list of available library images using GET /images). The new VM will be added to the application design.

HTTP Request

POST /applications/:appId/vms

Parameters

Parameter Required Description
appId yes The ID of the application.

Response

Status Code Description
200 OK The full application object after the update (including the new VM in the design).
400 Bad Request When the baseVmId field is missing from the request body.
404 Not Found When the application ID or the given image ID does not exist.

Delete VM from Application (Design)

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/applications/340955/vms/245293

Removes an existing VM from the application design according to its ID. This call does not update the cloud; application changes still need to be updated on the cloud using the publishUpdates call.

HTTP Request

DELETE /applications/:appId/vms/:vmId

Parameters

Parameter Required Description
appId yes The ID of the application.

Response

Status Code Description
200 OK When the full application object is updated (without VM is removed).
404 Not Found When the application ID or the given VM ID does not exist.

Get Application Documentation

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/168/documentation

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Returns the documentation of the application.

HTTP Request

GET applications/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
200 OK The documentation markdown.
404 Not Found When the specified application ID does not exist or the documentation does not exist.

Create Application Documentation

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Creates the application documentation.

HTTP Request

POST applications/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
201 Created The created documentation markdown.
404 Not Found When the specified application ID does not exist.

Update Application Documentation

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/applications/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some updated markdown code"
}
 Show full example

Updates the documentation of the application.

HTTP Request

PUT applications/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
201 Created The updated documentation markdown.
404 Not Found When the specified application ID does not exist.

Delete Application Documentation

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/applications/168/documentation

Deletes the documentation of the application.

HTTP Request

DELETE applications/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
204 No Content The documentation was deleted successfully.
404 Not Found When the specified application ID does not exist.

Tasks

Schedule New Application Task

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/applications/3405/tasks
{
    "action": "STOP",
    "scheduleInfo": {
        "start": null,
        "end": null,
        "cronExpression": "0 0 10 * * ?",
        "timezone": "UTC"
    },
    "description": "stop application 6 at 10 AM daily"
}
 Show full example

Example Response:

{
    "id": "131079",
    "entityId": "6",
    "entityType": "APPLICATION",
    "action": "STOP",
    "scheduleInfo": {
        "start": "1425821063194",
        "end": null,
        "cronExpression": "0 0 10  * * ?",
        "timezone": "UTC"
    },
    "args": {
        "appId": "6"
    },
    "description": "stop application 6 at 10 AM daily"
}
 Show full example

Example args parameter for BLUEPRINT:

{
    "args": {
        "namePrefix": "some name prefix",
        "description": "some description",
        "isOffline" : "true"
    }
}
 Show full example

Schedule a new application task.

HTTP Request

POST applications/:appId/tasks

Parameters

Parameter Required Description
appId yes The ID of the application.
action yes STOP/START/BLUEPRINT
scheduleInfo→start no When to start the task (enable time). If not provided, the task will start immediately.
scheduleInfo→end no When to end the task (disable time). If not provided, the task will never end.
scheduleInfo→cron no Cron expression for scheduling using Quartz Job Scheduler syntax.

Note: Due to the duration of tasks, the cron expression must be set with a resolution of 0 seconds.
scheduleInfo→delay no Sets a task to run once after the configured delay time (relative to now).
scheduleInfo→timezone no Sets the timezone of the given schedule info. If not provided, default “UTC” timezone will be used.
description no Task description (free text).
args no Task arguments in "key": "value" format. For START and STOP actions, no need to provide args. For BLUEPRINT, an argument of “isOffline” (boolean) is needed to determine if the application needs to be stopped before creating the blueprint. In addition, “namePrefix” (string) can be used to add a prefix for the name of the blueprint, and “description” can be used to add a (string) to the blueprint.

Response

Status Code Description
200 OK Successfully scheduled application task.
404 Not Found When the specified application ID does not exist.

Update a Task

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/applications/3405/tasks/123
{
    "action": "STOP",
    "scheduleInfo": {
        "start": null,
        "end": null,
        "cronExpression": "0 0 10 * * ?",
        "timezone": "UTC"
    },
    "description": "stop application 6 at 10 AM daily"
}
 Show full example

Example Response:

{
    "id": "123",
    "entityId": "6",
    "entityType": "APPLICATION",
    "action": "STOP",
    "scheduleInfo": {
        "start": "1425821063194",
        "end": null,
        "cronExpression": "0 0 10  * * ?",
        "timezone": "UTC"
    },
    "args": {
        "appId": "6"
    },
    "description": "stop application 6 at 10 AM daily"
}
 Show full example

Update an existing application task

HTTP Request

PUT applications/:appId/tasks/:taskId

Parameters

Parameter Required Description
appId yes The ID of the application.
taskId yes The ID of the task.
action yes STOP/START/BLUEPRINT
scheduleInfo→start no When to start the task (enable time). If not provided, the task will start immediately.
scheduleInfo→end no When to end the task (disable time). If not provided, the task will never end.
scheduleInfo→cron no Cron expression for scheduling using Quartz Job Scheduler syntax.

Note: Due to the duration of tasks, the cron expression must be set with a resolution of 0 seconds.
scheduleInfo→delay no Sets a task to run once after the configured delay time (relative to now).
scheduleInfo→timezone no Sets the timezone of the given schedule info. If not provided, default “UTC” timezone will be used.
description no Task description (free text).
args no Task arguments in "key": "value" format. For START and STOP actions, no need to provide args. For BLUEPRINT, an argument of “isOffline” (boolean) is needed to determine if first the application needs to be stopped before creating the blueprint. In addition - “namePrefix” (string) can be used to add a prefix for the name of the blueprint, and “description” (string) for the blueprint.

Response

Status Code Description
200 OK Successfully scheduled application task.
404 Not Found When the specified application ID or task ID does not exist.

Get All Application Tasks

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/3405/tasks

Example Response:

[
    {
    "id": "123",
    "entityId": "6",
    "entityType": "APPLICATION",
    "action": "STOP",
    "scheduleInfo": {
            "start": "1425821063194",
            "end": null,
            "cronExpression": "0 0 10  * * ?",
            "timezone": "UTC"
    },
    "args": {
        "appId": "6"
    },
    "description": "stop application 6 at 10 AM daily"
    }
]
 Show full example

Get all existing application tasks.

HTTP Request

GET applications/:appId/tasks

Parameters

Parameter Required Description
appId yes The ID of the application.

Response

Status Code Description
200 OK Application-related tasks.
404 Not Found When the specified application ID does not exist.

Get a Task

Example Request:

GET https://cloud.ravellosystems.com/api/v1/applications/3405/tasks/123

Example Response:

{
    "id": "123",
    "entityId": "6",
    "entityType": "APPLICATION",
    "action": "STOP",
    "scheduleInfo": {
        "start": "1425821063194",
        "end": null,
        "cronExpression": "0 0 10  * * ?",
        "timezone": "UTC"
    },
    "args": {
       "appId": "6"
    },
    "description": "stop application 6 at 10 AM daily"
}
 Show full example

Get an existing application task.

HTTP Request

GET applications/:appId/tasks/:taskId

Parameters

Parameter Required Description
appId yes The ID of the application.
taskId yes The ID of the task.

Response

Status Code Description
200 OK The required task.
404 Not Found When the specified application ID or task ID does not exist.

Delete Existing Task

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/applications/3405/tasks/123

Delete an existing application task.

HTTP Request

DELETE applications/:appId/tasks/:taskId

Parameters

Parameter Required Description
appId yes The ID of the application.
taskId yes The ID of the task.

Response

Status Code Description
204 No Content The task was successfully deleted.
404 Not Found When the specified application ID or task ID does not exist.

Delete All Application Tasks

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/applications/3405/tasks

Delete all existing application tasks.

HTTP Request

DELETE applications/:appId/tasks

Parameters

Parameter Required Description
appId yes The ID of the application.

Response

Status Code Description
204 No Content All application tasks were successfully deleted.
404 Not Found When the specified application ID does not exist.

Blueprints

Get Blueprints List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/blueprints

Example Response:

[
    {
        "creationTime": 1399987197973,
        "description": "temporary description",
        "design": {
            "state": "DONE"
        },
        "id": 46563346,
        "name": "Latest-Good-Version",
        "owner": "Ravello DevOps",
        "public": false,
        "published": false
    },
    {
        "creationTime": 1383029840929,
        "description": "1xHub vm (2cpu / 4G mem),\n3xNode vms (1cpu / 2G mem),\n6 webdriver Nodes: 3xFF, 3xChrome",
        "design": {
            "state": "DONE"
        },
        "id": 36929597,
        "name": "UI-Test-Farm",
        "owner": "Ravello Systems",
        "public": true,
        "published": false
    },
    {
        "creationTime": 1390208040444,
        "description": "Nginx, Tomcat 7 and Postgresql.\nA blueprint for developing Java applications.\nLog-in (to the VMs) with the user ravello (using a SSH key-pair)",
        "design": {
            "state": "DONE"
        },
        "id": 40304860,
        "name": "nginx-tomcat7-postgres",
        "owner": "Ravello Systems",
        "public": true,
        "published": false
    },
    {
        "creationTime": 1390207666635,
        "description": "Nginx, Tomcat 6 and Postgresql.\nA blueprint for developing Java applications.\nLog-in (to the VMs) with the user ravello (using a SSH key-pair)",
        "design": {
            "state": "DONE"
        },
        "id": 40304858,
        "name": "nginx-tomcat6-postgres",
        "owner": "Ravello Systems",
        "public": true,
        "published": false
    }
]
 Show full example

The list returned contains both the public and private blueprints. The difference between the two can be identified in the design/isPublic field.

Note: The returned list contains only general properties of the blueprints, and not all data. Use GET /blueprints/:id to get the full data for a specific blueprint.

HTTP Request

GET /blueprints

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of blueprint descriptions

Get Private Blueprints List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/organizations/1356321/blueprints

Example Response:

[
    {
        "creationTime": 1388402401698,
        "design": {
            "state": "DONE"
        },
        "id": 39288945,
        "name": "upgrade_for_bp",
        "owner": "Ravello DevOps",
        "public": false,
        "published": false
    },
    {
        "creationTime": 1388930000505,
        "design": {
            "state": "DONE"
        },
        "id": 39583763,
        "name": "system-integration-bp",
        "owner": "Ravello DevOps",
        "public": false,
        "published": false
    },
    {
        "creationTime": 1388072659876,
        "design": {
            "state": "ERROR"
        },
        "id": 39256074,
        "name": "System-M-Solo",
        "owner": "Ravello DevOps",
        "public": false,
        "published": false
    },
    {
        "creationTime": 1387993866230,
        "description": "rsyslog to papertailApp server & uts logs\nwith dns supporting pg9.3",
        "design": {
            "state": "DONE"
        },
        "id": 39190686,
        "name": "System-M-Solo-For-CI-bp",
        "owner": "Ravello DevOps",
        "public": false,
        "published": false
    }
]
 Show full example

Returns a list of all the blueprints under the authenticated user organization (private only). The returned list doesn’t contain the full blueprints, but only a general description of their properties. Use GET /blueprints/:id to get the full data for a specific blueprint.

HTTP Request

GET /organizations/:id/blueprints

Parameters

Parameter Required Description
id yes The ID of the organization.

Response

Status Code Description
200 OK List of blueprint descriptions
404 Not Found When the specified ID does not exist.

Get Blueprint

Example Request:

GET https://cloud.ravellosystems.com/api/v1/blueprints/1547252

Example Response:

{
    "creationTime": 1383029840929,
    "description": "1xHub vm (2cpu / 4G mem),\n3xNode vms (1cpu / 2G mem),\n6 webdriver Nodes: 3xFF, 3xChrome",
    "design": {
        "layout": {
            "groupLayoutItem": [
                {
                    "color": "#cbf2cc",
                    "dimension": {
                        "height": 335,
                        "width": 279
                    },
                    "groupId": 1365598382,
                    "isCollapsed": false,
                    "location": {
                        "x": 335,
                        "y": 140
                    }
                },
                {
                    "color": "#f7caa3",
                    "dimension": {
                        "height": 191,
                        "width": 148
                    },
                    "groupId": 48331275,
                    "isCollapsed": false,
                    "location": {
                        "x": 705,
                        "y": 185
                    }
                }
            ],
            "vmLayoutItem": [
                {
                    "location": {
                        "x": 60,
                        "y": 20
                    },
                    "vmId": 632912692
                },
                {
                    "location": {
                        "x": 55,
                        "y": 140
                    },
                    "vmId": 1607947792
                },
                {
                    "location": {
                        "x": 50,
                        "y": 250
                    },
                    "vmId": 392627182
                },
                {
                    "location": {
                        "x": 30,
                        "y": 40
                    },
                    "vmId": 333174996
                }
            ]
        },
        "network": {
            "dnsService": {
                "host": [
                    {
                        "ip": "10.0.0.3",
                        "name": "hub"
                    }
                ],
                "id": 5400643834426124577
            },
            "routerLegs": [
                {
                    "id": 903452285899415790,
                    "routerRef": 8275183158227619459,
                    "subnetRef": 957048693586009145
                }
            ],
            "routers": [
                {
                    "id": 8275183158227619459,
                    "isExternal": true
                }
            ],
            "subnets": [
                {
                    "dhcp": {
                        "active": true,
                        "id": 1794337069078874219,
                        "ipRangeBegin": "10.0.0.1",
                        "ipRangeEnd": "10.0.255.254"
                    },
                    "id": 957048693586009145,
                    "ip": "10.0.0.0",
                    "mask": "255.255.0.0",
                    "networkConnectionRefs": [
                        1352231843,
                        1979618543,
                        1404874089,
                        877599560
                    ]
                }
            ]
        },
        "networkFilter": {
            "accessAllowedByDefault": false,
            "filteringEnabled": false
        },
        "state": "DONE",
        "tags": [
            {
                "id": 48331275,
                "key": "_DESIGN_GROUP_TAG_",
                "value": "Hub"
            },
            {
                "id": 1365598382,
                "key": "_DESIGN_GROUP_TAG_",
                "value": "Linux-Nodes"
            }
        ],
        "vms": [
            {
                "applicationId": 36929597,
                "baseVmId": 36896880,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1383029841198,
                "description": "a ui node that has:\nDISPALY 0 : firefox\nDISPLAY 2: chrome\nconnects automatically to hub on startup and sets xvnc sessions",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "ide",
                        "controllerIndex": 0,
                        "controllerPciSlot": 1,
                        "id": 1653614466,
                        "imageFetchMode": "LAZY",
                        "imageFileChecksum": "c8309dfb9daffc96240c597967fc8908",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ubuntu-cloud-12.04-20130715.bin",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 5
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "nodelinux3"
                ],
                "id": 392627182,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Linux-NODE-Linux-3",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "default",
                            "generatedMac": "2c:c2:60:00:96:f5",
                            "index": 0,
                            "pciSlot": 1,
                            "useAutomaticMac": true
                        },
                        "id": 900396065,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": true,
                            "id": 1352231843
                        }
                    }
                ],
                "numCpus": 1,
                "os": "Linux",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                    {
                        "external": false,
                        "id": 327765842,
                        "name": "chrome",
                        "portRange": "6666",
                        "protocol": "TCP"
                    },
                    {
                        "external": false,
                        "id": 362576476,
                        "name": "ff",
                        "portRange": "5555",
                        "protocol": "TCP"
                    }
                ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1014388712,
                        "name": "vnc",
                        "portRange": "5900,5902",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 1034720364,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "tagRefs": [
                    {
                        "tagId": 1365598382
                    }
                ],
                "useCdn": false
            },
            {
                "applicationId": 36929597,
                "baseVmId": 36896880,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1383029841062,
                "description": "a ui node that has:\nDISPALY 0 : firefox\nDISPLAY 2: chrome\nconnects automatically to hub on startup and sets xvnc sessions",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "ide",
                        "controllerIndex": 0,
                        "controllerPciSlot": 1,
                        "id": 362458934,
                        "imageFetchMode": "LAZY",
                        "imageFileChecksum": "c8309dfb9daffc96240c597967fc8908",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ubuntu-cloud-12.04-20130715.bin",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 5
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "nodelinux1"
                ],
                "id": 632912692,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Linux-NODE-Linux-1",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "default",
                            "generatedMac": "2c:c2:60:0d:0c:fe",
                            "index": 0,
                            "pciSlot": 1,
                            "useAutomaticMac": true
                        },
                        "id": 484332619,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": true,
                            "id": 1979618543
                        }
                    }
                ],
                "numCpus": 1,
                "os": "Linux",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                    {
                        "external": false,
                        "id": 1803492662,
                        "name": "chrome",
                        "portRange": "6666",
                        "protocol": "TCP"
                    },
                    {
                        "external": false,
                        "id": 1707839185,
                        "name": "ff",
                        "portRange": "5555",
                        "protocol": "TCP"
                    }
                ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 1731095683,
                        "name": "vnc",
                        "portRange": "5900,5902",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 496930492,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "tagRefs": [
                    {
                        "tagId": 1365598382
                    }
                ],
                "useCdn": false
            },
            {
                "applicationId": 36929597,
                "baseVmId": 36896878,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1383029840934,
                "description": "Runs selenium hub as a service",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "ide",
                        "controllerIndex": 0,
                        "controllerPciSlot": 1,
                        "id": 379069895,
                        "imageFetchMode": "LAZY",
                        "imageFileChecksum": "c8309dfb9daffc96240c597967fc8908",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ubuntu-cloud-12.04-20130715.bin",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 5
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "hub"
                ],
                "id": 333174996,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 4
                },
                "name": "UI-Grid-HUB",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "default",
                            "generatedMac": "2c:c2:60:0c:3e:70",
                            "index": 0,
                            "pciSlot": 1,
                            "useAutomaticMac": true
                        },
                        "id": 216816924,
                        "ipConfig": {
                            "autoIpConfig": {
                                "reservedIp": "10.0.0.3"
                            },
                            "hasPublicIp": true,
                            "id": 877599560
                        }
                    }
                ],
                "numCpus": 2,
                "os": "Linux",
                "platform": "default",
                "rcu": 2.0,
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": false,
                        "id": 983220280,
                        "name": "ch",
                        "portRange": "6666",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 791220274,
                        "ip": "10.0.0.3",
                        "name": "hub",
                        "portRange": "4444",
                        "protocol": "TCP"
                    },
                    {
                        "external": false,
                        "id": 133242243,
                        "name": "ff",
                        "portRange": "5555",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 1015280412,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "tagRefs": [
                    {
                        "tagId": 48331275
                    }
                ],
                "useCdn": false
            },
            {
                "applicationId": 36929597,
                "baseVmId": 36896880,
                "bootOrder": [
                    "CDROM",
                    "DISK"
                ],
                "configurationManagement": {},
                "creationTime": 1383029841261,
                "description": "a ui node that has:\nDISPALY 0 : firefox\nDISPLAY 2: chrome\nconnects automatically to hub on startup and sets xvnc sessions",
                "hardDrives": [
                    {
                        "boot": true,
                        "controller": "ide",
                        "controllerIndex": 0,
                        "controllerPciSlot": 1,
                        "id": 1925491046,
                        "imageFetchMode": "LAZY",
                        "imageFileChecksum": "c8309dfb9daffc96240c597967fc8908",
                        "index": 0,
                        "loadingPercentage": 100,
                        "loadingStatus": "DONE",
                        "name": "ubuntu-cloud-12.04-20130715.bin",
                        "peripheral": false,
                        "size": {
                            "unit": "GB",
                            "value": 5
                        },
                        "type": "DISK"
                    }
                ],
                "hostnames": [
                    "nodelinux2"
                ],
                "id": 1607947792,
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "memorySize": {
                    "unit": "GB",
                    "value": 2
                },
                "name": "Linux-NODE-Linux-2",
                "networkConnections": [
                    {
                        "accessPort": true,
                        "device": {
                            "deviceType": "default",
                            "generatedMac": "2c:c2:60:0c:ae:f9",
                            "index": 0,
                            "pciSlot": 1,
                            "useAutomaticMac": true
                        },
                        "id": 155117682,
                        "ipConfig": {
                            "autoIpConfig": {},
                            "hasPublicIp": true,
                            "id": 1404874089
                        }
                    }
                ],
                "numCpus": 1,
                "os": "Linux",
                "platform": "default",
                "rcu": 1.0,
                "requiredServices": [
                    {
                        "external": false,
                        "id": 550636660,
                        "name": "ff",
                        "portRange": "5555",
                        "protocol": "TCP"
                    },
                    {
                        "external": false,
                        "id": 1382143132,
                        "name": "chrome",
                        "portRange": "6666",
                        "protocol": "TCP"
                    }
                ],
                "requiresHvm": false,
                "requiresKeypair": true,
                "suppliedServices": [
                    {
                        "external": true,
                        "id": 8073189,
                        "name": "ssh",
                        "portRange": "22",
                        "protocol": "TCP"
                    },
                    {
                        "external": true,
                        "id": 810433975,
                        "name": "vnc",
                        "portRange": "5900,5902",
                        "protocol": "TCP"
                    }
                ],
                "supportsCloudInit": true,
                "tagRefs": [
                    {
                        "tagId": 1365598382
                    }
                ],
                "useCdn": false
            }
        ]
    },
    "id": 36929597,
    "name": "UI-Test-Farm",
    "owner": "Ravello Systems",
    "public": true,
    "published": false
}
 Show full example

Returns the full blueprint data, including the blueprint properties, list of VMs, the saved network, and so on.

HTTP Request

GET /blueprints/:id

Parameters

Parameter Required Description
id yes The ID of the application.

Response

Status Code Description
200 OK Full blueprint
404 Not Found When the specified ID does not exist.

Create Blueprint

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/blueprints
{
    "applicationId": "245156",
    "blueprintName": "bpname",
    "offline": "true",
    "description": "This blueprint was created from my application"
}
 Show full example

Creates a new blueprint from an existing application. This action creates a snapshot of all running VMs, all network components, and all the properties of the application, enabling it to be re-created in other environments or versions.

HTTP Request

POST /blueprints

Parameters

Parameter Required Description
applicationId yes The ID of the application to create the blueprint from.
blueprintName yes The name of the new blueprint.
offline yes Specify whether to stop the machine prior to taking the snapshot, or take the snapshot online without turning the machine off.
description no The description of the new blueprint.

Response

Status Code Description
201 Created Full blueprint
400 Bad Request When some of the VMs are busy in other actions or not applicable for taking snapshots.
404 Not Found When the specified ID does not exist.

Delete Blueprint

Example Request with request body:

DELETE https://cloud.ravellosystems.com/api/v1/blueprints/1547252

Deletes the given blueprint from the organization blueprints list. The deletion is permanent.

HTTP Request

DELETE /blueprints/:id

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
204 No Content The blueprint was deleted successfully.
400 Bad Request When the blueprint is not stable for deleting (“in progress”).
404 Not Found When the specified ID does not exist.

Get All Publish Locations

Example Request:

GET https://cloud.ravellosystems.com/api/v1/blueprint/31028/publishLocations

Example Response:

[
    {
        "regionName": "us-central-1",
        "regionDisplayName": "US Central 1",
        "deprecated": false
    },
    {
        "regionName": "us-east-1",
        "regionDisplayName": "US East 1",
        "deprecated": false
    },
    {
        "regionName": "Virginia",
        "regionDisplayName": "Virginia",
        "deprecated": true
    }
]
 Show full example

Returns all the possible publish locations for the application that will be created from this blueprint, considering the storage and CPU needs. The list is sorted by costs – low to high.

HTTP Request

GET /blueprints/:id/publishLocations

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
200 OK Sorted list of all the possible publish locations.
404 Not Found When the specified ID does not exist.

Get Blueprint Documentation

Example Request:

GET https://cloud.ravellosystems.com/api/v1/blueprints/168/documentation

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Returns the documentation of the blueprint.

HTTP Request

GET blueprints/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
200 OK The documentation markdown.
404 Not Found When the specified blueprint ID does not exist or the documentation does not exist.

Create Blueprint Documentation

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/blueprints/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Creates the blueprint documentation.

HTTP Request

POST blueprints/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
201 Created The created documentation markdown.
404 Not Found When the specified blueprint ID does not exist.

Update Blueprint Documentation

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/blueprints/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some updated markdown code"
}
 Show full example

Updates the documentation of the blueprint.

HTTP Request

PUT blueprints/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
201 Created The updated documentation markdown.
404 Not Found When the specified blueprint ID does not exist.

Delete Blueprint Documentation

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/blueprints/168/documentation

Deletes the documentation of the blueprint.

HTTP Request

DELETE blueprints/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the blueprint.

Response

Status Code Description
204 No Content The documentation was deleted successfully.
404 Not Found When the specified blueprint ID does not exist.

Images

Get Images List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/images

The list returned contains both the public and private images. The difference between the two is identified using the isPublic field.

HTTP Request

GET /images

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of images descriptions

Get Private Images List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/organizations/1356321/images

Returns a list all the images under the authenticated user organization (private only). The returned list doesn’t contain the full images, but only a general description of their properties. Use GET /images/:id to get the full data for a specific image.

HTTP Request

GET /organizations/:id/images

Parameters

Parameter Required Description
id yes The ID of the organization.

Response

Status Code Description
200 OK List of images descriptions
404 Not Found When the specified ID does not exist.

Get Image

Example Request:

GET https://cloud.ravellosystems.com/api/v1/images/257112

Returns the full image data, including the image properties, list of hard drives, network connections and so on.

HTTP Request

GET /images/:id

Parameters

Parameter Required Description
id yes The ID of the image.

Response

Status Code Description
200 OK Full image
404 Not Found When the specified ID does not exist.

Create Image

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/images
{
    "applicationId": "1234",
    "blueprint": "false",
    "vmId": "123",
    "offline": "true",
    "imageName": "name"
}
 Show full example

Creates a new image from an existing blueprint VM or an application VM. To create an image from any VM in a blueprint, set the blueprint flag to true and give the correct blueprint id. To create an image from any VM in an application, published or not, there is no need for the blueprint flag (or set it to false) and to give the correct application id. When creating a blueprint from an application, one must specify the offline flag, which is used to indicate whether the snapshot should be taken online or offline (shuts down the VM first).

HTTP Request

POST /images

Parameters

Parameter Required Description
applicationId yes The ID of the application/blueprint to create the image from.
vmId yes The ID of the VM to create the image from.
offline yes Specify whether the to stop the machine prior to taking the snapshot, or take the snapshot online without turning the machine off.
blueprint no Set to True to create a new image from a blueprint VM.
imageName yes The name of the newly created image.

Response

Status Code Description
201 Created The full created image
400 Bad Request When the specified application, blueprint or VM ID does not exist, or when some of the parameters are not valid. Also returned when it is impossible to create the image because of deployment errors or busy machines.

Update Image

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/images/257112

Body: full image

Updates the image data and properties. The update here is full update, meaning the image will be replaced (elegantly) according to the given image object, meaning it is not possible to request a partial image, because that would simply delete the missing part from the actual VM. Example: if the method gets an empty list of hard drives, it will delete all the hard drives from the image. For more information about how to create and update the VMs, see Building an Application section.

HTTP Request

PUT /images/:id

Parameters

Parameter Required Description
id yes The ID of the image.
name yes The name of the image.
numCpus yes The number of CPUs in the VM.
memorySize yes The memory size defined for the VM. It’s composed of unit and value. Unit can be one of “GB”, “MB”, “KB”, “BYTE” and the value is long. Example:
"memorySize" : { "unit": "GB",   "value": 10 }
description no The description of the VM.
hostnames no List of hostnames for the VM.
platform no The original virtualization platform.
os no The operating system.
requiresKeypair no Specifies whether or not the system should enforce setting a public key for SSH connectivity.(If false, a preconfigured authentication mechanism is used.)
keypairId no When requiresKeypair set to true, set this field to the chosen key pair.
hardDrives no List of hard drives used in the VM.
networkConnections no List of network interfaces.
suppliedServices no List of supplied services. For simplicity, define a single external SSH service.
requiredServices no List of required services.
vmConfigurationManagement no Configuration management properties for this VM.

Response

Status Code Description
200 OK The full updated image
404 Not Found When the specified ID does not exist.

Delete Image

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/images/1547252

Deletes the given image from the organization’s image library list. The deletion is permanent.

HTTP Request

DELETE /images/:id

Parameters

Parameter Required Description
id yes The ID of the image to delete.

Response

Status Code Description
204 No Content The image was deleted successfully.
404 Not Found When the specified ID does not exist.

Get VM Documentation

Example Request:

GET https://cloud.ravellosystems.com/api/v1/images/168/documentation

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Returns the documentation of the VM.

HTTP Request

GET images/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the VM.

Response

Status Code Description
200 OK The documentation markdown.
404 Not Found When the specified VM ID does not exist or the documentation does not exist.

Create VM Documentation

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/images/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Creates the VM documentation.

HTTP Request

POST images/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the VM.

Response

Status Code Description
201 Created The created documentation markdown.
404 Not Found When the specified VM ID does not exist.

Update VM Documentation

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/images/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some updated markdown code"
}
 Show full example

Updates the documentation of the VM.

HTTP Request

PUT images/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the VM.

Response

Status Code Description
201 Created The updated documentation markdown.
404 Not Found When the specified VM ID does not exist.

Delete VM Documentation

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/images/168/documentation

Deletes the documentation of the VM.

HTTP Request

DELETE images/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the VM.

Response

Status Code Description
204 No Content The documentation was deleted successfully.
404 Not Found When the specified VM ID does not exist.

Disk Images

Get All Disk Images

Example Request:

GET https://cloud.ravellosystems.com/api/v1/diskImages

Example Response:

[
    {
        "id": 123,
        "name": "diskImage1",
        "creationTime": 1389527658504,
        "loadingStatus": "DONE",
        "loadingPercentage": 100,
        "owner": "John Doe",
        "size": {
            "value": 2588704,
            "unit": "KB"
        }
    },
    {
        "id": 456,
        "name": "diskImage2",
        "creationTime": 1390153875134,
        "loadingStatus": "DONE",
        "loadingPercentage": 100,
        "owner": "John Doe",
        "size": {
            "value": 1,
            "unit": "GB"
        }
    }
]
 Show full example

Returns a list of all the disk images - both public and under the authenticated user’s organization.

HTTP Request

GET /diskImages

Parameters

No parameters needed.

Response

Status Code Description
200 OK

Get Disk Image by ID

Example Request:

GET https://cloud.ravellosystems.com/api/v1/diskImages/257112

Example Response:

{
    "id": 123,
    "name": "diskImage1",
    "creationTime": 1389527658504,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "owner": "John Doe",
    "size": {
        "value": 2588704,
        "unit": "KB"
    }
}
 Show full example

Returns a disk image.

HTTP Request

GET /diskImages/:id

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
200 OK
404 Not Found When the specified ID does not exist.

Create a New Disk Image

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/images
{
    "id": 123,
    "name": "diskImage1",
    "creationTime": 1389527658504,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "owner": "John Doe",
    "size": {
        "value": 2588704,
        "unit": "KB"
    }
}
 Show full example

Example Response:

{
    "id": 123,
    "name": "diskImage1",
    "creationTime": 1389527658504,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "owner": "John Doe",
    "size": {
        "value": 2588704,
        "unit": "KB"
    }
}
 Show full example

Creates a new disk image from an existing blueprint VM, application VM or library VM. For all the above possibilities the VM ID and the disk ID within the VM must be specified.

HTTP Request

POST /diskImages

Parameters

Parameter Required Description
vmId yes The ID of the VM to create the disk image from.
diskId yes The ID of the disk to create the disk image from.
applicationId no The ID of the application/blueprint to create the disk image from.
offline yes Specify whether to stop the machine prior to taking the snapshot or take the snapshot online without turning the machine off.
blueprint no Set this flag to True to create a new disk image from a blueprint VM.
diskImage yes Properties of the new disk image. Example:
"diskImage" : {
   "name": "diskImage1",
   "description": "my disk image"
}

Response

Status Code Description
201 Created
400 Bad Request When the specified application/blueprint/VM/disk does not exist, or some of the parameters are not valid. Also returned when it is impossible to create the disk image because of deployment errors or busy machines.

Update Disk Image

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/diskImages/257112
{
    "id": 123,
    "name": "diskImage1",
    "creationTime": 1389527658504,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "owner": "John Doe",
    "size": {
        "value": 2588704,
        "unit": "KB"
    }
}
 Show full example

Example Response:

{
    "id": 123,
    "name": "diskImage1",
    "creationTime": 1389527658504,
    "loadingStatus": "DONE",
    "loadingPercentage": 100,
    "owner": "John Doe",
    "size": {
        "value": 2588704,
        "unit": "KB"
    }
}
 Show full example

Update a disk image.

HTTP Request

PUT /diskImages/:id

Parameters

Parameter Required Description
id yes The ID of the disk image.
name yes The name of the disk image.
description no The description of the VM.
size yes The disk size that is required to deploy this image. It’s composed of unit and value. Unit can be one of “GB”, “MB”, “KB”, “BYTE” and the value is long. Example:
"size" : { "unit": "GB", "value": 10 }

Response

Status Code Description
200 OK The updated disk image.
404 Not Found When the specified ID does not exist.

Delete Disk Image

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/diskImages/1547252

Deletes the given disk image from the library. The deletion is permanent.

HTTP Request

DELETE /diskImages/:id

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
204 No Content The disk image was deleted successfully.
404 Not Found When the specified ID does not exist.

Get Disk Image Documentation

Example Request:

GET https://cloud.ravellosystems.com/api/v1/diskImages/168/documentation

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Returns the documentation of the disk image.

HTTP Request

GET /diskImages/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
200 OK The documentation markdown.
404 Not Found When the specified disk image ID does not exist or the documentation does not exist.

Create Disk Image Documentation

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/diskImages/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some markdown code"
}
 Show full example

Creates the disk image documentation.

HTTP Request

POST /diskImages/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
201 Created The created documentation markdown.
404 Not Found When the specified disk image ID does not exist.

Update Disk Image Documentation

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/diskImages/168/documentation
{
    "value" : "some markdown code"
}
 Show full example

Example Response:

{
    "value" : "some updated markdown code"
}
 Show full example

Updates the documentation of the disk image.

HTTP Request

PUT /diskImages/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
201 Created The updated documentation markdown.
404 Not Found When the specified disk image ID does not exist.

Delete Disk Image Documentation

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/diskImages/168/documentation

Deletes the documentation of the disk image.

HTTP Request

DELETE /diskImages/:id/documentation

Parameters

Parameter Required Description
id yes The ID of the disk image.

Response

Status Code Description
204 No Content The documentation was deleted successfully.
404 Not Found When the specified disk image ID does not exist.

Key Pairs

Get Key Pairs List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/keypairs

Example Response:

[
    {
        "id": 33629974,
        "name": "demo"
    },
    {
        "id": 33659975,
        "name": "demo2"
    },
    {
        "id": 33783510,
        "name": "sys"
    }
]
 Show full example

Returns a list of all the key pairs in the authenticated user organization. The key pairs returned consist of only the ID and name; the key (private or public) itself is not returned.

HTTP Request

GET /keypairs

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of key pairs.

Get Key Pair

Example Request:

GET https://cloud.ravellosystems.com/api/v1/keypairs/34068721

Example Response:

{
    "id": 34068721,
    "name": "key1"
}
 Show full example

Returns a single key pair according to its ID.

HTTP Request

GET /keypairs/:id

Parameters

Parameter Required Description
id yes The ID of the key pair.

Response

Status Code Description
200 OK Key pair data.
404 Not Found When the specified ID does not exist.

Create Key Pair

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/keypairs
{
    "name": "amit2",
    "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCI/NF80..."
}
 Show full example

Example Response:

{
    "id": 34068721,
    "name": "key1"
}
 Show full example

Creates a new key pair in the organization’s key pair list. The public key must be specified in OpenSSH format.

HTTP Request

POST /keypairs

Parameters

Parameter Required Description
name yes The name of the key pair.
publicKey yes The public key of the new key pair.

Response

Status Code Description
201 Created The created key pair without the public key.
400 Bad Request When the key pair already exists or the supplied public key is not a valid OpenSSH public key.

Generate Random Key Pair

Example Request:

POST https://cloud.ravellosystems.com/api/v1/keypairs/generate

Example Response:

{
    "privateKey": "-----BEGIN RSA PRIVATE     KEY-----\nMIIEpQIBe...",
    "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAA4DAQABAA47sv3AB7sIQB..."
}
 Show full example

Creates a new random key pair. This is a utility method that is used only to create a pair of private and public keys. Use POST /keypairs to add the generated key to the list of key pairs.

HTTP Request

POST /keypairs/generate

Parameters

No parameters needed.

Response

Status Code Description
200 OK Random key pair.

Update Key Pair

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/keypairs/34068721
{
    "name": "new_key_name"
}
 Show full example

Example Response:

{
    "id": 34068721,
    "name": "new_key_name"
}
 Show full example

Updates the key pair given. It is only possible to update the keypair name.

HTTP Request

PUT /keypairs/:id

Parameters

Parameter Required Description
id yes The ID of the key pair to update.
name yes The key pair name.

Response

Status Code Description
200 OK The update key pair.
400 Bad Request When the key pair name is already taken.
404 Not Found When the specified ID does not exist.

Delete Key Pair

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/keypairs/34068721

Deletes the given key pair from the organization’s key pairs list. Note that there might still be running VMs that are using the key. It will still be possible to retrieve it using GET /keypairs/:id, along with a “deleted” flag.

HTTP Request

DELETE /keypairs/:id

Parameters

Parameter Required Description
id yes The ID of the key pair to delete.

Response

Status Code Description
204 No Content The key pair was deleted successfully.
404 Not Found When the specified ID does not exist.

Elastic IPs

Get Elastic IPs List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/elasticIps

Example Response:

[
    {
        "creationTime": "1401629683401",
        "id": 7372807,
        "ip": "85.190.180.105",
        "ownerAppId": 52101371,
        "ownerAppName": "App1",
        "ownerVmId": "1222727556",
        "ownerVmName": "Ubuntu 12.04.1 vanilla1",
        "elasticIpLocation": {
             "type": "REGIONAL",
             "name": "us-central-1",
             "displayName": "US Central 1",
             "cloudRegion": {
                 "name": "us-central-1",
                 "displayName": "US Central 1",
                 "deprecated": false
             }
        }
    },
    {
        "creationTime": "1420711654507",
        "id": 13074527,
        "ip": "85.190.181.151",
        "ownerAppId": 53839357,
        "ownerAppName": "App2",
        "ownerVmId": "635770049",
        "ownerVmName": "Vm1", 
        "elasticIpLocation": {
             "type": "GLOBAL",
             "name": "Sydney",
             "displayName": "RTB-Sydney"
        }
    }
]
 Show full example

Returns a list of all the elastic IP addresses in the organization pool. The details for each elastic IP in the list include the IP address. In addition, if this IP address is assigned to a specific VM of a specific application, the details will include the application name.

HTTP Request

GET /elasticIps

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of organization elastic IPs

Create Elastic IP

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/elasticIps
{
    "name": "my_elastic_ip",
    "description": "This elastic IP is used in my application",
    "locationType": "REGIONAL", 
    "locationName": "us-central-1"
}
 Show full example

Example Response:

{
    "id": 1736706,
    "ip": "85.190.183.20",
    "name": "my_elastic_ip",
    "creationTime": "1439898479611",
    "elasticIpLocation": {
        "type": "REGIONAL",
        "name": "us-central-1",
        "displayName": "US Central 1",
        "cloudRegion": {
            "name": "us-central-1",
            "displayName": "US Central 1",
            "deprecated": false
        }
    }
}
 Show full example

Adds a new random elastic IP address to the organization pool. Once taken, the IP address is exclusively reserved for the use of the organization, until it is removed from the organization pool.

In case of a trial that has expired, all the elastic IP addresses are removed and the organization pool is cleared.

HTTP Request

POST /elasticIps

Parameters

Parameter Required Description
location yes The location of the IP address pool where the elastic IP address will be created.
name no The name of the elastic IP address (for documentation purposes).
description no The description of the elastic IP address (for documentation purposes).

Response

Status Code Description
200 OK The IP address of the newly created elastic IP.
403 Forbidden When the quota for public or elastic IP addresses is exceeded, or the organization accessibility status is disabled.

Delete Elastic IP

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/elasticIps/50.112.0.0

Removes an elastic IP from the organization pool, but only If this IP is NOT currently assigned to any VM. If it is assigned, the request will fail.

HTTP Request

DELETE /elasticIps/:ip

Parameters

Parameter Required Description
id yes The IP address of the elastic IP to delete.

Response

Status Code Description
204 No Content The elastic IP address was deleted successfully.
404 Not Found The specified elastic IP was not found in the organization pool.

Get Locations of IP Address Pools

Example Request:

GET https://cloud.ravellosystems.com/api/v1/elasticIps/locations/

Example Response:

[
   {
        "type": "GLOBAL",
        "name": "Sydney",
        "displayName": "RTB-Sydney"   
   },
   {
        "type": "REGIONAL",
        "name": "us-central-1",
        "displayName": "US Central 1",
        "cloudRegion": {
            "name": "us-central-1",
            "displayName": "US Central 1",
            "deprecated": false
        }
   }
]
 Show full example

Returns a list of all the available locations of IP address pools. The user can use these names in creating a new elastic IP address.

HTTP Request

GET /elasticIps/locations

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of IP pool locations.

Organizations

Get User’s Organization

Example Request:

GET https://cloud.ravellosystems.com/api/v1/organization

Example Response:

{
    "accountStatus": "REGULAR",
    "id": 8,
    "organizationName": "Org Name"
}
 Show full example

Returns the authenticated user organization’s details.

HTTP Request

GET /organization

Parameters

Parameter Required Description
id yes The ID of the organization.

Response

Status Code Description
200 OK Organization details

Get Organization By ID

Example Request:

GET https://cloud.ravellosystems.com/api/v1/organizations/8

Example Response:

{
    "accountStatus": "REGULAR",
    "id": 8,
    "organizationName": "Org Name"
}
 Show full example

Returns the organization details according to its ID.

HTTP Request

GET /organizations/:id

Parameters

Parameter Required Description
id yes The ID of the organization.

Response

Status Code Description
200 OK The ID of the organization.
404 Not Found When the specified ID does not exist.

Update Organization

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/organizations/8
{
    "organizationName": "New Name"
}
 Show full example

Example Response:

{
    "accountStatus": "REGULAR",
    "id": 8,
    "organizationName": "New Name"
}
 Show full example

Updates the organization details.

HTTP Request

PUT /organizations/:id

Parameters

Parameter Required Description
id yes The ID of the organization.
organizationName yes The name of the organization.

Response

Status Code Description
200 OK Updated organization details
404 Not Found When the specified ID does not exist.

Get Organization Users List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/organizations/143566/users

Example Response:

[
    {
        "email": "ravello_user@ravello.com",
        "enabled": true,
        "id": 261641,
        "invitationTime": 1375714064288,
        "name": "Ravello user",
        "organization": 8,
        "roles": ["USER"],
        "surname": "Ravello user",
        "uuid": "Admin_665823ef-bc29-4a8d-a247-c871369e03f1"
    },
    {
        "email": "ravello@ravello.com",
        "enabled": true,
        "id": 261645,
        "invitationTime": 1375714064268,
        "name": "Ravello admin",
        "organization": 8,
        "roles": ["USER", "ADMIN"],
        "surname": "Ravello admin",
        "uuid": "Admin_367f722e-481b-4f26-b033-a179274f871f"
    }
]
 Show full example

Returns a list of all the users in the given organization. This is an administrator permitted operation only.

HTTP Request

GET /organizations/:id/users

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of users.

Users

Get the Authenticated User

Example Request:

GET https://cloud.ravellosystems.com/api/v1/user

Example Response:

[
    {
        "email": "ravello_user@ravello.com",
        "enabled": true,
        "id": 261641,
        "invitationTime": 1375714064288,
        "name": "Ravello user",
        "nickname": "nickname",
        "organization": 8,
        "roles": ["USER"],
        "surname": "Ravello user",
        "uuid": "Admin_665823ef-bc29-4a8d-a247-c871369e03f1"
    }
]
 Show full example

Returns the authenticated user details.

HTTP Request

GET /user

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of users

Get Users List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/users
GET https://cloud.ravellosystems.com/api/v1/organizations/143566/users

Example Response:

[
    {
        "email": "ravello_user@ravello.com",
        "enabled": true,
        "id": 261641,
        "invitationTime": 1375714064288,
        "name": "Ravello user",
        "nickname": "nickname",
        "organization": 8,
        "roles": ["USER"],
        "surname": "Ravello user",
        "uuid": "Admin_665823ef-bc29-4a8d-a247-c871369e03f1"
    },
    {
        "email": "ravello@ravello.com",
        "enabled": true,
        "id": 261645,
        "invitationTime": 1375714064268,
        "name": "Ravello admin",
        "nickname": "nickname",
        "organization": 8,
        "roles": ["USER", "ADMIN"],
        "surname": "Ravello admin",
        "uuid": "Admin_367f722e-481b-4f26-b033-a179274f871f"
    }
]
 Show full example

Returns a list of all the users in the authenticated user organization.

HTTP Request

GET /users

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of users

Invite User

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1//organizations/85146/users
{
    "email": "invite@gmail.com",
    "name": "User1",
    "surname": "User1Sur"
}
 Show full example

Invites a new user to the authenticated admin’s organization. When inviting a user who was invited before, the invitationTime will be updated but not the other details.

HTTP Request

POST /organizations/:orgid/users

Parameters

Parameter Required Description
orgid yes The ID of the organization.
email yes The email address of the user.
name yes The name of the user.
surname yes The surname of the user.

Response

Status Code Description
201 Created The created user details.
404 Not Found When the specified ID does not exist.

Update User

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/users/261641
{
    "email": "invite@gmail.com",
    "name": "newName",
    "nickname": "nickname",
    "roles": ["USER", "ADMIN"],
    "surname": "newSurname"
}
 Show full example

Example Response:

{
    "email": "ravello_user@ravello.com",
    "enabled": true,
    "id": 261641,
    "invitationTime": 1375714064288,
    "name": "newName",
    "nickname": "nickname",
    "organization": 8,
    "roles": ["USER"],
    "surname": "newSurname",
    "uuid": "665823ef-bc29-4a8d-a247-c871369e03f1"
}
 Show full example

Updates the user details.

HTTP Request

PUT /users/:id

Parameters

Parameter Required Description
id yes The ID of the user.
name yes The name of the user.
surname yes The surname of the user.
roles yes A list of existing/new roles for the user. To add another admin to the organization, add the role “ADMIN” to the user.

Note: Only an organization administrator can assign the ADMIN role.

Response

Status Code Description
200 OK Updated user details
400 Bad Request Invalid name/surname.
404 Not Found When the specified ID does not exist.

Change Password

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/users/1436125/changepw
{
    "existingPassword": "123456",
    "newPassword": "a!b@c#d$"
}
 Show full example

Changes the user password.

HTTP Request

POST /users/:id/changepw

Parameters

Parameter Required Description
id yes The ID of the user.
existingPassword yes The current password for the user.
newPassword yes The new password.

Response

Status Code Description
204 No Content Password successfully changed.
400 Bad Request New password is too weak, existing password mismatch.
404 Not Found When the specified ID does not exist.

Shares

Get List of Shares

Example Request:

GET https://cloud.ravellosystems.com/api/v1/shares
GET https://cloud.ravellosystems.com/api/v1/shares?sharingUserId=3&targetEmail=c7b41e7e2e4.mail@gmail.com

Example Response:

[
    {
        "id" :  3,
        "sharingUserId" :  33027,
        "targetEmail" :  "50ac3b0872d941bea.mail@gmail.com",
        "sharedResourceType" :  "LIBRARY_VM",
        "sharedResourceId" :  33054,
        "time" :  1430181781881
    },
    {
        "id" :  2,
        "sharingUserId" :  33027,
        "targetEmail" :  "c7b41e7e2e4.mail@gmail.com",
        "sharedResourceType" :  "LIBRARY_VM",
        "sharedResourceId" :  33054,
        "time" :  1430181781537
    }
]
 Show full example

Returns a list of share records, optional filters could be used.

HTTP Request

GET /shares

Parameters

Parameter Required Description
sharingUserId no The ID of the sharing user.
targetEmail no The email of the user whom we share the resource with.
sharedResourceType no Could be one of the following: BLUEPRINT, LIBRARY_VM, DISK_IMAGE.
sharedResourceId no The resource ID.

Response

Status Code Description
200 OK List of users
403 Forbidden The user doesn’t have get permission over the “Share” record

Share Specific Resource

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/shares/
{
    "targetEmail" :  "c7b41e7e2e@gmail.com",
    "sharedResourceType" :  "LIBRARY_VM",
    "sharedResourceId" :  33054
}
 Show full example

Example Response:

{
    "id" :  2,
    "sharingUserId" :  33027,
    "targetEmail" :  "c7b41e7e2e@gmail.com",
    "sharedResourceType" :  "LIBRARY_VM",
    "sharedResourceId" :  33054,
    "time" :  1430181781537
}
 Show full example

Share a specific resource with a target user .

HTTP Request

POST /shares

Parameters

Parameter Required Description
targetEmail yes The email address of the user the share the resource with.
sharedResourceType yes Should be one of the following: BLUEPRINT, LIBRARY_VM, DISK_IMAGE
sharedResourceId yes The resource ID

Response

Status Code Description
201 Created The Share details
403 Forbidden The sharing user doesn’t have share permissions for the specified resource.

Delete Share Data by ID

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/shares/1436125

Unshare specific resource.

HTTP Request

DELETE /shares/:id

Parameters

Parameter Required Description
id yes The ID of the share record.

Response

Status Code Description
204 No Content The share record was deleted successfully.
403 Forbidden When the user has no permission to performs unshare operation with the specified Share ID.
404 Not Found When the specified ID does not exist.

Communities

Get Community by ID

Example Request:

GET https://cloud.ravellosystems.com/api/v1/communities/1

Example Response:

{
    "id" :  1,
    "name" :  "Ravello PUBLIC Community",
    "description" :  "Ravello PUBLIC Community",
    "owner" :  "John Smith",
    "type" :  "PUBLIC"
}
 Show full example

Returns a community details by community ID.

HTTP Request

GET /communities/:id

Parameters

Parameter Required Description
id yes The community ID

Response

Status Code Description
200 OK Specified Community
403 Forbidden The user doesn’t have get permission over the “Community” resource
404 Not Found The community with specified ID wasn’t found

Get List of Communities

Example Request:

GET https://cloud.ravellosystems.com/api/v1/communities

Example Response:

[
    {
        "id" :  1,
        "name" :  "Ravello PUBLIC Community",
        "description" :  "Ravello PUBLIC Community",
        "owner" :  "John Smith",
        "type" :  "PUBLIC"
    }
]
 Show full example

Returns a list of communities.

HTTP Request

GET /communities

Parameters

No parameters required.

Response

Status Code Description
200 OK List of communities

Ephemeral Access Tokens

Get Ephemeral Access Tokens

Example Request:

GET https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens

Example Response:

[
   {
        "id":119,
        "owner":"user88cc71bcd2 Automatic",
        "name":"Ephemeral Token",
        "creationTime":1439921994556,
        "expirationTime":1440181194556,
        "token":"UsTP7puH8YYfdUM2p4goVPDapPnpmATwiqczVKLO0Y9jLl0Dhny8BTaM6pmN9VqD",
        "permissions":[
            {
                "id":462,
                "actions":[
                "READ"
                ],
                "resourceType":"LIBRARY_VM",
                "filterCriterion":{
                "id":133,
                "type":"COMPLEX",
                "index":null,
                "operator":"And",
                "name":null,
                "criteria":[
                    {
                        "id":134,
                        "type":"SIMPLE",
                        "index":null,
                        "operator":"Equals",
                        "name":null,
                        "criteria":null,
                        "propertyName":"ID",
                        "operand":32926
                    }
                ],
                "propertyName":null,
                "operand":null
                }
            }
        ]
   }
]
 Show full example

Ephemeral access tokens allow temporary access to resources in Ravello without having a Ravello user. This token should be passed as a query param named “token” or as an HTTP header named “X-Ephemeral-Token-Authorization”. The query param and the header can be passed to any API URL call. When the token is used, there is no need to provide other authorization information for the applicable resources.

This call returns a list of ephemeral access tokens in the organization that the current logged-in user has permissions to get (not only those the logged in user has created). The token permissions are defined in the json permissions list field. See Simple Filter Section at Permission Management to read more about the permission structure.

HTTP Request

GET /ephemeralAccessTokens

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of ephemeral access tokens

Get Ephemeral Access Token by ID

Example Request:

GET https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens/119
{
    "someKey1" : "someValue1",
    "someKey2" : "someValue2",
    "someKey3" : "someValue3",
    "someKey4" : "someValue4"
}
 Show full example

Example Response:

{
    "id":119,
    "owner":"user88cc71bcd2 Automatic",
    "name":"Ephemeral Token",
    "creationTime":1439921994556,
    "expirationTime":1440181194556,
    "token":"UsTP7puH8YYfdUM2p4goVPDapPnpmATwiqczVKLO0Y9jLl0Dhny8BTaM6pmN9VqD",
    "permissions":[
        {
            "id":462,
            "actions":[
            "READ"
            ],
            "resourceType":"LIBRARY_VM",
            "filterCriterion": {
                "id":133,
                "type":"COMPLEX",
                "index":null,
                "operator":"And",
                "name":null,
                "criteria": [
                    {
                        "id":134,
                        "type":"SIMPLE",
                        "index":null,
                        "operator":"Equals",
                        "name":null,
                        "criteria":null,
                        "propertyName":"ID",
                        "operand":32926
                    }
                ],
                "propertyName":null,
                "operand":null
            }
        }
    ]
}
 Show full example

Returns an ephemeral access token by ID.

HTTP Request

GET /ephemeralAccessTokens/:id

Parameters

Parameter Required Description
id yes The ephemeral access token ID.

Response

Status Code Description
200 OK The ephemeral access token
403 Forbidden The user doesn’t have read permissions for ephemeral access token with the given ID.
404 Not Found The ephemeral access token with specified ID wasn’t found.

Create Ephemeral Access Token

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens
{
    "name" :  "Ephemeral Token"
}
 Show full example

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens
{
    "name" :  "Ephemeral Token",
    "description" :  "Ephemeral Token for a LIBRARY_VM with ID: 32921",
    "permissions" : [
        {
            "actions" : [
                "READ"
            ],
            "resourceType" :  "LIBRARY_VM",
            "filterCriterion" : {
                "type" :  "COMPLEX",
                "operator" :  "And",
                "criteria" : [
                    {
                        "type" :  "SIMPLE",
                        "operator" :  "Equals",
                        "propertyName" :  "ID",
                        "operand" :  32921
                    }
                ]
            }
        }
    ]
}
 Show full example

Example Response:

{
    "id": 917513,
    "owner": "Ravello User",
    "name": "Ephemeral Token",
    "creationTime": 1439976990596,
    "expirationTime": 1440236190596,
    "token": "kcUek4r5eOWu873Au90YLNufi5abosUBzstCzw2rAvO2Ru84MZD0VamUtsKHbFmF"
}
 Show full example

Creates an ephemeral access token.

HTTP Request

POST /ephemeralAccessTokens

Parameters

Parameter Required Description
name yes The ephemeral access token name.
expirationTime no The token expiration time in milliseconds from 1-1-1970 UTC. If the expiration time is not provided, the default value is three days.
description no A description of the ephemeral access token.
permissions no The list of permissions associated with the ephemeral access token.

Response

Status Code Description
201 Created The ephemeral access details.
403 Forbidden The logged in user doesn’t have permissions to create the specified resources.

Update Existing Ephemeral Access Token by ID

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens/240
{
    "id" :  240,
    "name" :  "Ephemeral Token",
    "description" :  "Updated Ephemeral Token for a LIBRARY_VM with ID: 32922",
    "expirationTime" :  1440204595127,
    "permissions" : [
        {
            "actions" : [
                "READ"
            ],
            "resourceType" :  "LIBRARY_VM",
            "filterCriterion" : {
                "type" :  "COMPLEX",
                "operator" :  "And",
                "criteria" : [
                    {
                        "type" :  "SIMPLE",
                        "operator" :  "Equals",
                        "propertyName" :  "ID",
                        "operand" :  32922
                    }
                ]
            }
        }
    ]
}
 Show full example

Example Response:

{
    "id" :  240,
    "name" :  "Ephemeral Token",
    "description" :  "Updated Ephemeral Token for a LIBRARY_VM with ID: 32922",
    "expirationTime" :  1440204595127,
    "permissions" : [
        {
            "id"  : 441,
            "actions" : [
                "READ"
            ],
            "resourceType" :  "LIBRARY_VM",
            "filterCriterion" : {
                "id"  : 89,
                "type" :  "COMPLEX",
                "operator" :  "And",
                "criteria" : [
                    {
                        "id"  : 90,
                        "type" :  "SIMPLE",
                        "operator" :  "Equals",
                        "propertyName" :  "ID",
                        "operand" :  32922
                    }
                ]
            }
        }
    ]
}
 Show full example

Updates the ephemeral access token by ID.

HTTP Request

PUT /ephemeralAccessTokens/:id

Parameters

Parameter Required Description
id yes The ID of the ephemeral access token.

Response

Status Code Description
200 OK The ephemeral access token was updated successfully.
403 Forbidden When the user has no permission to perform update operation for the specified ephemeral access token ID.
404 Not Found When the specified ID does not exist.

Delete Ephemeral Access Token by ID

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/ephemeralAccessTokens/119

Deletes ephemeral access token by ID.

HTTP Request

DELETE /ephemeralAccessTokens/:id

Parameters

Parameter Required Description
id yes The ID of the ephemeral access token.

Response

Status Code Description
204 No Content The ephemeral access token was deleted successfully.
403 Forbidden When the user does not have permission to perform delete operation with the specified ephemeral access token ID.
404 Not Found When the specified ID does not exist.

Permissions Groups

Permissions Management

Parameters Example - The following json defines a permission to read, create and update an application with ID=1:

{
  "actions": [
    "READ",
    "CREATE",
    "UPDATE"
  ],
  "resourceType": "APPLICATION",
  "filterCriterion": {
    "type": "COMPLEX",
    "operator": "And",
    "criteria": [
      {
        "type": "SIMPLE",
        "operator": "Equals",
        "propertyName": "ID",
        "operand": "1"
      }
    ]
  }
}
 Show full example

Parameters Example - The following json defines a permission to read, update and delete owned applications:

{
  "actions": [
    "READ",
    "UPDATE",
    "DELETE"
  ],
  "resourceType": "APPLICATION",
  "filterCriterion": {
    "type": "COMPLEX",
    "operator": "And",
    "criteria": [
      {
        "type": "SIMPLE",
        "operator": "Equals",
        "propertyName": "ownerID",
        "variable": "Self"
      }
    ]
  }
}
 Show full example

Parameters Example - The following json defines a permission to delete any of the blueprints in the system:

{
    "actions": [
        "DELETE"
    ],
    "resourceType": "BLUEPRINT"
}
 Show full example

Filter Example - The following json defines a permission to delete any of the blueprints in the system:

{
  "type": "COMPLEX",
  "operator": "And",
  "criteria": [
    {
      "type": "SIMPLE",
      "operator": "Equals",
      "propertyName": "ownerID",
      "operand": "1"
    },
    {
      "type": "COMPLEX",
      "operator": "Or",
      "criteria": [
        {
          "type": "SIMPLE",
          "operator": "Equals",
          "propertyName": "ID",
          "operand": "2"
        },
        {
          "type": "SIMPLE",
          "operator": "Equals",
          "propertyName": "ID",
          "operand": "3"
        }
      ]
    }
  ]
}
 Show full example

Overview

The ability of users to perform various actions in the Ravello depends on the permissions assigned to that user. In Ravello, a user’s permissions are determined by the permission groups to which the user is assigned.

Permissions

A permission group is a set of permitted actions on a certain set of resources. The set of resources is defined by the resource type (e.g., application, key pair) and a filter that defines the resource instances included (e.g., all or only those with specific IDs).

Different levels of permissions can be added for each resource type in a permission group in keeping with the needs of your organization and the functionality required by different types of users.

To add a new permission to a permission group, you need to select the resource for which want to configure permissions. You can do so by fetching the permission descriptors (click here to learn how), which are a list of objects that describe for each resource type the supported actions and properties. After locating the desired resource in the descriptors list, choose a subset of the actions that it supports, and create your own filter based on its properties and the operators they support.

Parameters

Parameter Required Description
actions yes A list of actions that should be allowed on the filtered resources.
resourceType yes The type of resource that should be allowed.
filterCriterion no The filter that defines the subset of objects of the given resource type that the actions should be allowed on. If a filter is not supplied, the permission will apply to all objects of the resource type.

Filters

A filter is a structure that allows us to define a subset of instances of a specific resource type by a specific condition. For example, a filter can define all the applications of team1 and of team2, by their IDs, names, and in the future - tags. In order to understand the structure of the filter, let’s define two kinds of filters: simple and complex. Simple filters contain a property name, a comparison operator, and an operand (e.g., application ID equals 1). Complex filters contain a logical operator (and, or) and a set of sub-filters, which can either be simple or complex.

Simple Filter Parameters

Parameter Required Description
type yes Value should be “SIMPLE”.
propertyName yes The name of the resource property of the condition. Make sure the property is supported by the given resource type, according to the corresponding resource descriptor.
operator yes The comparison operator (e.g. equals, greater than) of the condition. Make sure the operator is supported by the given resource property, according to the corresponding property descriptor.
operand Use operand or variable The operand of the condition.
variable Use operand or variable A variable operand for the condition. The variable will be evaluated dynamically. For example, “Self”, will be evaluated as the logged-in user.

Complex Filter Parameters

Parameter Required Description
type yes Value should be “COMPLEX”.
operator yes The logical operator of the condition. The possible values are “And” and “Or”.
criteria yes A list of filters.

Get Permissions Groups List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/permissionsGroups

Example Request:

GET https://cloud.ravellosystems.com/api/v1/permissionsGroups?userId=5461548391

Example Response:

[
  {
    "id": "2",
    "creationTime": "1422389660000",
    "name": "User",
    "description": "Default user group, to which new users are automatically added.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "2",
        "actions": [
          "READ"
        ],
        "resourceType": "LIBRARY_VM"
      },
      {
        "id": "3",
        "actions": [
          "READ"
        ],
        "resourceType": "DISK_IMAGE"
      }
    ]
  },
  {
    "id": "3",
    "creationTime": "1422389660443",
    "name": "QA",
    "description": "The QA team permissions group, containing full permissions on their application.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "10",
        "actions": [
          "READ",
          "CREATE",
          "UPDATE",
          "DELETE",
          "EXECUTE"
        ],
        "resourceType": "APPLICATION",
        "filterCriterion": {
          "id": "1",
          "type": "COMPLEX",
          "operator": "And",
          "criteria": [
            {
              "id": "2",
              "type": "SIMPLE",
              "operator": "Equals",
              "propertyName": "ID",
              "operand": "1"
            }
          ]
        }
      }
    ]
  }
]
 Show full example

Returns a list of all the permissions groups. Add the query parameter userId to get permissions groups assigned to a specific user.

HTTP Request

GET /permissionsGroups

Query Parameters

Parameter Required Description
userId no The user ID for which the permissions groups are assigned.

Response

Status Code Description
200 OK List of permissions groups

Get Permissions Group

Example Request:

GET https://cloud.ravellosystems.com/api/v1/permissionsGroups/2

Example Response:

{
    "id": "2",
    "creationTime": "1422389660000",
    "name": "User",
    "description": "Default user group, to which new users are automatically added.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "2",
        "actions": [
          "READ"
        ],
        "resourceType": "LIBRARY_VM"
      },
      {
        "id": "3",
        "actions": [
          "READ"
        ],
        "resourceType": "DISK_IMAGE"
      }
    ]
  }
 Show full example

Returns a single permissions group according to its ID.

HTTP Request

GET /permissionsGroups/:id

Parameters

Parameter Required Description
id yes The ID of the permissions group.

Response

Status Code Description
200 OK Permissions group data
404 Not Found When the specified ID does not exist.

Create Permissions Group

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/permissionsGroups
{
    "name": "QA",
    "description": "The QA team permissions group, containing full permissions on their application.",
    "permissions": [
      {
        "actions": [
          "READ",
          "CREATE",
          "UPDATE",
          "DELETE",
          "EXECUTE"
        ],
        "resourceType": "APPLICATION",
        "filterCriterion": {
          "type": "COMPLEX",
          "operator": "And",
          "criteria": [
            {
              "type": "SIMPLE",
              "operator": "Equals",
              "propertyName": "ID",
              "operand": "1"
            }
          ]
        }
      }
    ]
  }
 Show full example

Example Response:

{
    "id": "3",
    "creationTime": "1422389660443",
    "name": "QA",
    "description": "The QA team permissions group, containing full permissions on their application.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "10",
        "actions": [
          "READ",
          "CREATE",
          "UPDATE",
          "DELETE",
          "EXECUTE"
        ],
        "resourceType": "APPLICATION",
        "filterCriterion": {
          "id": "1",
          "type": "COMPLEX",
          "operator": "And",
          "criteria": [
            {
              "id": "2",
              "type": "SIMPLE",
              "operator": "Equals",
              "propertyName": "ID",
              "operand": "1"
            }
          ]
        }
      }
    ]
  }
 Show full example

Creates a new permissions group.

HTTP Request

POST /permissionsGroups

Parameters

Parameter Required Description
name yes The name of the permissions group.
description no A description of the permissions group.
permissions no The set of the permissions that the permissions group contains.

Response

Status Code Description
201 Created The created permissions group

Update Permissions Group

Example Request with request body:

PUT https://cloud.ravellosystems.com/api/v1/permissionsGroups/2

{
    "id": "2",
    "creationTime": "1422389660000",
    "name": "User",
    "description": "Default user group, to which new users are automatically added.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "2",
        "actions": [
          "READ"
        ],
        "resourceType": "LIBRARY_VM"
      },
      {
        "actions": [
          "READ"
        ],
        "resourceType": "DISK_IMAGE"
      }
    ]
 }
 Show full example

Example Response:

{
    "id": "2",
    "creationTime": "1422389660000",
    "name": "User",
    "description": "Default user group, to which new users are automatically added.",
    "owner": "Jane Doe",
    "permissions": [
      {
        "id": "2",
        "actions": [
          "READ"
        ],
        "resourceType": "LIBRARY_VM"
      },
      {
        "id": "3",
        "actions": [
          "READ"
        ],
        "resourceType": "DISK_IMAGE"
      }
    ]
 }
 Show full example

Updates the given permissions group.

HTTP Request

PUT /permissionsGroups/:id

Parameters

Parameter Required Description
id yes The ID of the permissions group to update.
name yes The permissions group name.
description no A description of the permissions group.
permissions no The set of the permissions that the permissions group contains.

Response

Status Code Description
200 OK The updated permissions group
400 Bad Request
404 Not Found When the specified ID does not exist.

Delete Permissions Group

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/permissionsGroups/3

Deletes the given permissions group.

HTTP Request

DELETE /permissionsGroups/:id

Parameters

Parameter Required Description
id yes The ID of the permissions group to delete.

Response

Status Code Description
204 No Content The permissions group was deleted successfully.
404 Not Found When the specified ID does not exist.

Get Permissions Group Users List

Example Request:

GET https://cloud.ravellosystems.com/api/v1/permissionsGroups/3/users

Example Response:

[
    {
        "email": "ravello_user@ravello.com",
        "enabled": true,
        "id": 261641,
        "invitationTime": 1375714064288,
        "name": "Ravello user",
        "organization": 8,
        "roles": ["USER"],
        "surname": "Ravello user",
        "uuid": "Admin_665823ef-bc29-4a8d-a247-c871369e03f1"
    },
    {
        "email": "ravello@ravello.com",
        "enabled": true,
        "id": 261645,
        "invitationTime": 1375714064268,
        "name": "Ravello admin",
        "organization": 8,
        "roles": ["USER", "ADMIN"],
        "surname": "Ravello admin",
        "uuid": "Admin_367f722e-481b-4f26-b033-a179274f871f"
    }
]
 Show full example

Returns a list of all the users in the permissions group.

HTTP Request

GET /permissionsGroups/:id/users

Parameters

Parameter Required Description
id yes The ID of the permissions group.

Response

Status Code Description
200 OK List of the users in the permissions group
404 Not Found When the specified ID does not exist.

Add User to Permissions Group

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/permissionsGroups/3/users
{
    "userId": "3"
}
 Show full example

Adds a user to the permissions group.

HTTP Request

POST /permissionsGroups/:id/users

Parameters

Parameter Required Description
id yes The ID of the permissions group to update.

Response

Status Code Description
204 Not Content The user was added to the permissions group successfully.

Delete User from Permissions Group

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/permissionsGroups/3/users/5

Deletes the given user from the permissions group.

HTTP Request

DELETE /permissionsGroups/:id/users/:userId

Parameters

Parameter Required Description
id yes The ID of the permissions group to update.
userId yes The ID of the user to remove from the permissions group.

Response

Status Code Description
204 Not Content The user was removed to the permissions group successfully.
404 Not Found When the specified ID does not exist.

Describe Permissions Group

Example Request:

GET https://cloud.ravellosystems.com/api/v1/permissionsGroups/describe

Example Response:

[
  {
    "resourceType": "BILLING_INFORMATION",
    "propertyDescriptors": [],
    "actions": [
      "READ"
    ]
  },
  {
    "resourceType": "BLUEPRINT",
    "propertyDescriptors": [
      {
        "name": "description",
        "type": "String",
        "operators": [
          "Equals",
          "NotEquals"
        ]
      },
      {
        "name": "name",
        "type": "String",
        "operators": [
          "Equals",
          "StartsWith",
          "NotEquals"
        ]
      },
      {
        "name": "ownerID",
        "type": "Long",
        "operators": [
          "NotEquals",
          "Equals"
        ]
      },
      {
        "name": "ID",
        "type": "Long",
        "operators": [
          "NotEquals",
          "Equals"
        ]
      }
    ],
    "actions": [
      "DELETE",
      "READ",
      "UPDATE",
      "CREATE"
    ]
  }
]
 Show full example

Returns a list of resource permission descriptors that describe the configuration possibilities of this resource permission, such as supported properties and actions.

HTTP Request

GET /permissionsGroups/describe

Parameters

No parameters needed.

Response

Status Code Description
200 OK List of the permission descriptors

Notifications

Search Notifications

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/notifications/search
{
    "maxResults": 100,
    "appId": "1234",
    "notificationLevel": "ERROR",
    "dateRange": {
        "startTime": 1375367161480,
        "endTime": 1375367161525
    }
}
 Show full example

Example Response:

{
    "dateRange": {
        "endTime": 1398783526448,
        "startTime": 0
    },
    "notification": [
        {
            "eventProperties": [
                {
                    "key": "message",
                    "value": "User named Ravello admin (ID 8) logged in."
                },
                {
                    "key": "userName",
                    "value": "Ravello admin"
                },
                {
                    "key": "organizationid",
                    "value": "8"
                }
            ],
            "eventTimeStamp": 1398783451152,
            "eventType": "LOGIN",
            "notificationLevel": "INFO",
            "operationId": "517400694456467",
            "relatedEntityId": 8,
            "userId": 8
        },
        {
            "appId": 360453,
            "eventProperties": [
                {
                    "key": "message",
                    "value": "Snapshoting after VM Webserver - Sample Application stopped."
                },
                {
                    "key": "targetVmId",
                    "value": "360461"
                },
                {
                    "key": "snapshotPercent",
                    "value": "100"
                },
                {
                    "key": "userName",
                    "value": "Ravello admin"
                },
                {
                    "key": "isAppDeleted",
                    "value": "false"
                },
                {
                    "key": "organizationid",
                    "value": "8"
                }
            ],
            "eventTimeStamp": 1398782184149,
            "eventType": "VM_SNAPSHOTTING_AFTER_STOP",
            "notificationLevel": "INFO",
            "operationId": "381374970923201",
            "projectId": 8,
            "relatedEntityId": 1562869916,
            "userId": 8
        }
    ]
}
 Show full example

Returns a list of all notifications regarding the given criteria.

HTTP Request

POST /notifications/search

Parameters

Parameter Required Description
appId no The application ID to get notifications from.
notificationLevel no The level of the notifications to search.
maxResults no Returns only this amount of notifications.
dateRange no Returns only notifications triggered in the given date range. Date range format is:
{"startTime": 1375367161480, "endTime": 1375367161525}

Response

Status Code Description
200 OK Notifications returned successfully.

User Alerts

Get User Alerts

Example Request:

GET https://cloud.ravellosystems.com/api/v1/userAlerts

Example Response:

[
    {
        "id": 458753,
        "eventName": "VM_STARTED",
        "userId": 8
    }
]
 Show full example

Returns a list of all the alerts that a specific user is registered to. If the user is an administrator this call returns a list of all the alerts that the organization was registered too.

HTTP Request

GET /userAlerts

Parameters

No parameters needed.

Status Code Description
200 OK List of user alerts

Post User Alerts

Example Request with request body:

POST https://cloud.ravellosystems.com/api/v1/userAlerts
{
    "eventName": "VM_STARTED"
}
 Show full example

Registers a user to an alert. Once registered this user will get an email every time this event happens to any VM in any application that belongs to his organization.

HTTP Request

POST /userAlerts

Parameters

Parameter Required Description
eventName yes The name of the event that the user wants to register to (taken from /events).
userId no This parameter is only valid for an organization administrator who wants to register a user in his organization.

Response

Status Code Description
200 OK The user was successfully registered to this event.
403 Forbidden When the user in userId is not in your organization or when you are not an administrator.

Delete User Alerts

Example Request:

DELETE https://cloud.ravellosystems.com/api/v1/userAlerts/458753

Unregister a user from a specific alert.

HTTP Request

DELETE /userAlerts/

Parameters

Parameter Required Description
id yes The id of the userAlert.

Response

Status Code Description
204 No Content The user was successfully unregistered to this event.

Events

Get Events

Example Request:

GET https://cloud.ravellosystems.com/api/v1/events

Example Response:

[
    "VM_ERROR"
    "VM_TERMINATING"
    "VM_ERROR_DEPLOY"
    "VM_ERROR_TERMINATE"
    "VM_ERROR_START"
    "VM_ERROR_RESTART"
    "VM_ERROR_STOP"
    "VM_ERROR_REDEPLOY"
    "VM_ERROR_REPAIR"
]
 Show full example

Returns a list of all the events in the system

HTTP Request

GET /events

Parameters

No parameters needed.

Status Code Description
200 OK List of events

Billing

Get Billing Details

Example Request:

GET https://cloud.ravellosystems.com/api/v1/billing
GET https://cloud.ravellosystems.com/api/v1/billing?year=2014&month=08

Example Response:

[
    {
        "charges": [
            {
                "productRate": 0.01,
                "summaryPrice": 0.05,
                "productCount": 5,
                "productType": "ELASTIC_IP",
                "productUname": "ELASTIC_IP",
                "productName": "Elastic IP",
                "unitName": "Elastic IPs/Hour"
            },
            {
                "productRate": 0.12,
                "summaryPrice": 0.12,
                "productCount": 0.97,
                "productType": "VM_STORAGE_MB",
                "productUname": "VM_STORAGE_MB",
                "productName": "Library, GB",
                "unitName": "GB/Month"
            }
        ],
        "applicationId": 0
    },
    {
        "charges": [
            {
                "productRate": 0.12,
                "summaryPrice": 0.01,
                "productCount": 0.12,
                "productType": "DISKSPACE_MB",
                "productUname": "DISKSPACE_MB",
                "productName": "Disk Space, GB",
                "unitName": "GB/Month"
            },
            {
                "productRate": 0.01,
                "summaryPrice": 0.02,
                "productCount": 2,
                "productType": "IP_ADDRESS",
                "productUname": "IP_ADDRESS",
                "productName": "IP Addresses",
                "unitName": "IPs/Hour"
            },
            {
                "productRate": 0.3,
                "summaryPrice": 0.3,
                "productCount": 1,
                "productType": "MINIMUM",
                "productUname": "MINIMUM.BASIC.COST_OPTIMIZED",
                "productName": "Minimum Cost Optimized Basic Tier",
                "unitName": "Units/Hour"
            },
            {
                "productRate": 0.15,
                "summaryPrice": 0.14,
                "productCount": 0.93,
                "productType": "NETWORKING_MB",
                "productUname": "NETWORKING_MB",
                "productName": "External TX Networking",
                "unitName": "GB"
            }
        ],
        "applicationId": 98
    }
]
 Show full example

Returns a list of all the organization’s applications and their detailed charges from the beginning of the month. Add the query parameters year and month to get the list from the beginning of the given month in the given year.

HTTP Request

GET /billing

Parameters

Parameter Required Description
year no The year of the charges. Format: four-digit year - YYYY
month no The month of the charges. Format: two-digit month - MM
Status Code Description
200 OK List of the organization’s applications and their detailed charges

Building an Application

Overview

The Ravello application is described by two different aspects: the design and the deployment.

The application lifecycle is as follows: first the user must create a design - the application draft that describes the virtual machines and the connections between them and to the outside world.

Then the user can publish the application, taking performance-optimized or cost-optimized approach. Later the user can view the deployment aspect of the application, which contains the virtual machines and their state on the cloud.

Creating a New Application

To create an application from a blueprint, simply specify the chosen blueprint ID:

POST https://cloud.ravellosystems.com/api/v1/applications
{
    "name": "MyApp",
    "description" : "My Application Description",
    "baseBlueprintId": 51904660
}
 Show full example

To create an application from scratch, the user must define the VMs within the design aspect of the application. Example: an application with one VM, with a static IP address:

POST https://cloud.ravellosystems.com/api/v1/applications
{
    "name": "MyApp2",
    "description": "My Application Description",
    "design": {
        "vms": [
            {
                "baseVmId": 10,
                "name": "ubuntu-12-4-cloudinit",
                "description": "ubuntu-12-4-cloudinit",
                "legacyMode": false,
                "loadingPercentage": 100,
                "loadingStatus": "DONE",
                "vmOrderGroupId": 1,
                "stopTimeOut": 600,
                "powerOffOnStopTimeOut" : false,
                "memorySize": {
                  "unit": "GB",
                  "value": 2
                },
                "numCpus": 1,
                "hardDrives": [
                  {
                    "boot": true,
                    "controller": "virtio",
                    "controllerIndex": 0,
                    "controllerPciSlot": 0,
                    "index": 0,
                    "name": "ravello-ubuntu-12.04.2.qcow2",
                    "size": {
                        "unit": "GB",
                        "value": 15
                    },
                    "type": "DISK"
                  }
                ],
                "networkConnections": [
                  {
                    "accessPort": true,
                    "device": {
                        "deviceType": "default",
                        "mac": "2c:c2:60:16:47:0b",
                        "index": 0,
                        "useAutomaticMac": true
                    },
                    "ipConfig": {
                      "hasPublicIp": true,
                      "staticIpConfig": {
                          "gateway": "10.0.2.1",
                          "ip": "10.0.2.10",
                          "mask": "255.255.0.0"
                      }
                    }
                  }
                ],
                "suppliedServices": [
                  {
                      "external": true,
                      "ip": "10.0.2.10",
                      "name": "ssh",
                      "portRange": "22",
                      "protocol": "TCP"
                  },
                  {
                      "external": false,
                      "ip": "10.0.2.10",
                      "name": "https",
                      "portRange": "443",
                      "protocol": "TCP"
                  }
                ]
            }
        ],
    "vmOrderGroups":
        [
           {"id": 1, "name": "group1", "order": 0, "delay": 30},
           {"id": 2, "name": "group1", "order": 1, "delay": 40},
           {"id": 3, "name": "group2", "order": 2, "delay": 20},
           {"id": 4, "name": "group3", "order": 3, "delay": 0}
        ],
        "stopVmsByOrder": false
    }
}
 Show full example

There are two ways to create a new application: from an existing blueprint or from scratch.

Setting the VM Start/Stop Order

It is possible to set the order in which VMs start and stop.

If a VM is not defined as part of a group, it will start immediately and impose no dependency on other groups.

All VMs in group N will be started together and will impose a delay on the VMs in group N+1. The VMs in the N+1 group will start a configurable number of seconds after the last VM in group N that was scheduled to start has reached a final state. Final state is defined as started or in error. Note: If the user chooses to manually start some of the VMs in group N, the VMs that were not started are considered in end state (whether they are started, stopped or in error).

The Stop order can be configured via the stopVmsByOrder. true stops the VMs in reverse order; false simultaneously stops the VMs. (The default setting is false).

In the JSON structure above:

Application Objects

Application Properties

Name Description
id The ID of the application.
name The name of the application.
owner The name of the application owner, updated automatically by Ravello according to the creator of the application.
description The description of the application.
baseBlueprintId The ID of the blueprint that the application is based on.
blueprintName The name of the blueprint that the application is based on.
designDiffersFromDeployment A boolean flag indicating there are changes in the design that have not been published to the cloud yet.
published A flag indicating whether the application is published to the cloud.
creationTime The time and date when the application was created.
version A serial value indicating the application metadata version, automatically increased upon application save or publish.
nextStopTask A structure that contains two fields:

1. time (type: long) - the UTC trigger time of the next stop task.

2. id (type: long) - the ID of the next stop task.

Application Inner Objects

Name Description
design Describes the saved application and all the user’s changes.
deployment Describes the application on the cloud, exactly as it was when it was last published. The differences between the design and deployment can be viewed by comparing, for example, two VMs with the same ID.

Design Properties

Name Description
state Relevant only for blueprints, indicates the blueprint state of snapshotting. Possible values are: UNKNOWN, ERROR, ERROR_UPLOADING, DELETING, DELETED, PAUSED, UPLOADING, SAVING, PENDING, PARSING, DONE.
vmOrderGroups Group VMs according to the starting order. See more details under .
stopVmsByOrder Specifies whether the VMs should be stopped according to the reverse starting order. See more details under .

Design Inner Objects

Name Description
vms A list of the virtual machines in the application design (whether published or not).
network The application designed network - includes the subnet, routers, and more.
networkFilter Contains rules about who can access the application and how.
validationMessages Contains information about the validity of the design. Every design error will be contained in this list of validation messages.

Deployment Properties

Name Description
totalActiveVms The number of published VMs.
totalErrorVms The number of VMs that were published on the cloud but encountered an error during or after publishing.
expirationTime The time when the application will be stopped automatically.
expirationType The application’s current auto-stop state. Possible values are: STOPPED_BY_USER, AUTO_STOPPING, AUTO_STOPPED.
publishStartTime The time when the application was started.
publishOptimization Determines whether the application will be cost or performance optimized. Possible values: COST_OPTIMIZED, PERFORMANCE_OPTIMIZED.
vmOrderGroups Groups VMs according to the starting order. See more details under .
stopVmsByOrder Specifies whether the VMs should be stopped according to the reverse starting order. See more details under .

Deployment Inner Objects

Name Description
vms A list of the virtual machines in the application deployment (published or currently publishing).
cloudRegion Contains information about the the region where the application is published.
network The application designed network - includes the subnet, routers, and more. Generally, the user does not need to construct this object as it automatically built after every change.
networkFilter Contains rules about who can access the application and how.

VM Properties

Name Description
id The ID of the VM.
name The name of the image.
description The description of the VM.
creationTime The creation time of the VM (when it was first saved).
memorySize The memory size defined for the VM. It’s composed of unit and value. Unit can be one of “GB”,“MB”, “KB”, “BYTE” and the value is long. Example:
"memorySize" : { "unit": "GB", "value": 10 }
numCpus The number of CPUs in the VM.
platform The original virtualization platform, possible values: “DEFAULT”, “V2-ESX”
os The operating system.
supportsCloudInit Set this to true if the VM has cloud-init installed. Currently we support vanilla cloud-init v0.7.5 and up (Ubuntu 14.04 and later, Fedora Cloud images, etc). See here for more details.
userData Cloud-init’s behaviour can be configured using this field. See available formats here.
requiresKeypair Specifies whether or not the system should enforce setting a public key for SSH connectivity.(If false, a pre-configured authentication mechanism is used.)
keypairId When requiresKeypair set to true, set this field to the chosen key pair.
hostnames List of hostnames for the VM.
applicationId The ID of the application that this VM belongs to.
legacyMode Enables legacy mode for higher virtual hardware compatibility. Important: legacy mode is much slower than the default mode. We strongly advise to use it only after a discussion with us.
loadingStatus This field has two different meanings. On a design VM, this holds the loading status of the image that the VM is based on, since one can add a new VM to the design even if it’s not fully loaded yet.

Possible upload values: UPLOADING, PARSING, PENDING, PAUSED, SAVING, DONE, DELETING, DELETED, ERROR_UPLOADING, ERROR, UNKNOWN.

On a published VM, if a snapshot process is running (happens also automatically on stop), this field returns the status of that process.

Possible snapshot values: POST_SNAPSHOTTING, PRE_SNAPSHOTTING, SNAPSHOTTING, DONE.
loadingPercentage When the loading status of the VM is UPLOADING or SNAPSHOTTING, this indicates the percentage of data already uploaded or saved as snapshot.
baseVmId The ID of the library VM that this VM is based on.
biosUuid The BIOS unique identifier used for licensing or checking vendor hardware platform.
cpuIds Supported CPU features exposed to guest VMs.
bootOrder Specifies the boot order for the VM, for example: [‘CDROM’, 'DISK’]
rtc Real Time Clock - Sets the timezone for the VM. This is an object containing a String mode and a long number seconds. The possible modes are ABSOLUTE or RELATIVE and the seconds should set the timezone.

Example:
"rtc" : { "mode": "RELATIVE", "seconds": 7200 }


Default:
{ "mode": "RELATIVE", "seconds": 0 }
displayDevice The display device for this VM. Make sure your VM has the required driver for the selected device. Possible values are: “default”, “vmware-svga”, “VGA” (upper case).
vmOrderGroupId Links the VM with the group for setting VMs start/stop order. See more details under Setting the VM Start/Stop Order section.
stopTimeOut Time to wait for VM to stop successfully, default is 20 minutes.

VM Inner Objects

Name Description
hardDrives List of hard drives used in the VM.
networkConnections List of network interfaces.
suppliedServices List of supplied services. For simplicity, define a single external SSH service.
requiredServices List of required services.

Hard Drive Properties (No Inner Objects)

Name Description
id The ID of the hard drive.
name The name of the hard drive.
boot Specifies whether this hard drive is a boot disk for the VM or not.
size The size of the hard drive. It’s composed of unit and value. Unit can be one of “GB”, “MB”, “KB”, “BYTE” and the value is long. Example:
'memorySize' : { 'unit': 'GB', 'value': 100 }
index The index of the hard drive in the hard drives list.
type The type of hard drive (DISK and/or CDROM).
baseDiskImageId If this disk was created based on a library disk image (rather than from scratch or based on an image that is a part of a whole VM), this field contains the image ID. Note: If a snapshot has been taken, this ID does not change, because the disk is still based on the same image.
baseDiskImageName The name of the library disk image that this disk is based on, meaning: the name of the image disk that has the ID stored in baseDiskImageId field.
controller The hard drive controller type. Possible values include: PVSCSI - ParaVirtual SCSI Controller IDE - Virtual IDE Controller VIRTIO - Virtual SCSI LSI53C895A - LSI Logic Generic LSI53C1030 - LSI Logic Parallel LSISAS1068 - LSI Logic SAS
controllerIndex The index of the hard drive controller in the VM.
controllerPciSlot The PCI slot of the hard drive controller.
loadingStatus This field has two different meanings. On a design VM, this holds the loading status of the hard disk on the image that the VM is based on.

Possible upload values: UPLOADING, PARSING, PENDING, PAUSED, SAVING, DONE, DELETING, DELETED, ERROR_UPLOADING, ERROR, UNKNOWN.

On a published VM, if a snapshot process is running (happens also automatically on stop), this field returns the status of that process.

Possible snapshot values: POST_SNAPSHOTTING, PRE_SNAPSHOTTING, SNAPSHOTTING, DONE.
loadingPercentage When the loading status of the VM is UPLOADING or SNAPSHOTTING, this indicates the percentage of data already uploaded or saved as snapshot.

Cloud Region Properties

Name Description
name The unique name of the region where the application is published (for example: “us-central-1”).
displayName The display name of the region where the application is published (for example: “US Central 1”).
deprecated Indicates whether the cloud region is deprecated. If so, then it will be unsupported soon.

Network Connection Properties

Name Description
id The ID of the network connection.
name The name of the network connection (documentation purposes).
accessPort A boolean flag specifying whether this connection is an access port or a trunk port (or neither if no VLAN is configured).
vlanTag The VLAN tag of this network connection.

Network Connection Inner Objects

Name Description
device Information about the technical details for the network connection.
ipConfig The main IP configuration defined on this network connection. Contains the IP information defined on the physical network interface, such as the FQDN, elastic IP uses etc.
additionalIpConfig Additional IP configurations that can be defined on the network connection. See ipConfig field for more information.

Network Connection Device Object

Name Description
mac The preconfigured MAC address for the NIC.
useAutomaticMac When no MAC address is specified, this can be set to true to automatically generate a MAC address for the network connection.
index The index of the network connection in the network connection interfaces list.
pciSlot The PCI slot for the network connection.
deviceType The device type. Possible values include: E1000, VMXNET3, VMXNET, VIRTIO, PCNENT, RTL8139, NE2000.
generatedMac If useAutomaticMac field is set, this field holds the automatically generated MAC address.

IP Configuration Device Object

Name Description
id The ID of the IP configuration object.
fqdn The fully qualified domain name associated with this IP.
staticIpConfig Specifies the static IP configuration, including IP address, mask, DNS, and gateway.
autoIpConfig Specifies the DHCP IP configuration, includingreservedIp and allocatedIp. For example:

"ipConfig" : {
   "autoIpConfig": {
      'allocatedIp': '10.0.0.4'
   }
}
publicIp If the object is configured to use a public IP, this field holds the public IP address.
externalAccessState Specifies external access. Possible value are:
CONDITIONAL_PUBLIC_IP - Assigns a public IP address when at least one external service is connected to this configuration.

ALWAYS_PUBLIC_IP - Always uses a public IP address in this configuration. This allows outgoing traffic through this IP configuration to use a unique public IP address.

ALWAYS_PORT_FORWARDING - Always use port forwarding.
elasticIpAddress If the objectis configured to use an elastic IP, this will hold the elastic IP address.
needElasticIp Specifies whether to use elastic IP for this IP.

Any Service Properties

Name Description
id The ID of the service.
name The name of the service.
description A description of the use of the service (documentation purposes).
ip The IP that the service is configured on.
portRange The port range for the service.
protocol The protocol of the service (TCP, UDP, IP, SSH, HTTP, HTTPS, or RDP).
external Specifies whether the service is accessible from the external world.
externalPort Generated by Ravello. If there is no public IP for this VM, an external port will be mapped to portRange field (in this case it can be only a single port). For example, SSH on port 22 can be accessed via 10000. External users should use 'ssh -p 10000 FQDN’

Extra Properties for Supplied Service

Name Description
ipConfigLuid The ID of the IP configuration associated with the service.
enableSnat Enable source NATwhen accessing this service from the external world.
ipProtocol To be used to allow non-TCP/UDP protocols. In this case 'protocol’ should be IP and ipProtocol. The protocol is a number between 1 and 255 inclusive to denote an IP Protcol number (for example: 1 is ICMP, 6 is TCP and 17 is UDP), or 0 for ANY to denote any /all protocols.

Extra Properties for Required Service

Name Description
suppliedServiceRef The ID of the supplied service that this service requires.

Network Filter Properties and Inner Objects

Name Description
accessAllowedByDefault Specifies whether new rules defined in the incomingNetwork field are ALLOW rules by default. Set it to false to change the default policy to DENY.
filteringEnabled Specifies whether filtering using the list of rules defined in incomingNetwork field is enabled.
blockOutgoingTraffic Specifies whether all outgoing network traffic from the application should be blocked.
incomingNetwork List rules to allow/deny access from specific subnets.

Incoming Network

Name Description
subnet The subnet to allow/deny acess from.
netmask The netmask for the subnet.
accessAllowed Allows or denies access from this subnet.
priority The priority of the rule, compared to the other rules. Specifies the order of the rules.

General Request Structure

Examples (Using cURL):

- curl -v -X PUT -d @/path/to/jsonfile -H "Content-Type: application/json" -H "Accept: application/json" --user ravello@ravello.com:password https://cloud.ravellosystems.com/api/v1/applications/414244

The json file is a file containing json data requested by the specific call.

- curl -v -H "Accept: application/xml" --user ravello@ravello.com:password https://cloud.ravellosystems.com/api/v1/applications/

HTTP Methods

The allowed methods are currently GET, POST, PUT, and DELETE for retrieving, creating, updating, and deleting resources, respectively. Not all resources support all actions, see the detailed resources API.

HTTP Headers

Content-Type: This header must be set to the format of the sent request. Our servers currently support two types of formats: application/json and application/xml. Set this header to one of these formats to specify the format of the request.

Accept: An optional header to specify the format of the received response. Set this header to application/xml to get XML response or application/json to get JSON response.

X-LongToString: An optional header, causing all long-based values to be returned as strings. For example, instead of receiving applicationId=123456, you will get applicationId=”123456”. This option is recommended for JavaScript based clients that are using the API, as JavaScript doesn’t support 64bit numbers (rounding is automatically done for those types).

HTTP Response Codes

There are several response codes that could result from executing a request to the Ravello API.

You can see the possible codes for each request, summarized below:

Status Code Description
200 OK The operation has finished successfully.
201 Created The resource was created successfully.
202 Accepted The required operation has begun and will finish in the future.
400 Bad Request When the given parameters for the request does not match the requirements.
401 Unauthorized When trying to call any API request without authorization.
403 Forbidden Can occur in several cases: Attempting operations with insufficient permission levels, or when quota exceeded.
404 Not Found When the given parameters (IDs) don’t refer to any existing resource, or when there is no such method.
405 Method Not Allowed When trying to access a resource with the wrong or unsupported HTTP method (for example, using POST instead of GET).
409 Conflict When trying to access a resource while it’s busy performing other actions.