Quick Start

Last updated: Dec 14th, 2016

Compute API

The Nodilex Compute API is based on an Apache Cloudstack infrastructure, therefore some of the CloudStack API methods are not supported on the Nodilex COmpute API. Here you will find a list of all the basic methods with several ways to test it like CloudMonkey, Postman and some code samples.

Getting Started

Making Requests

All Nodilex API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following whether in HTTPS exclusively:

  • Nodilex API URL: This is the web services API entry point (https://api.nodilex.com/compute)
  • Command: The web services command you wish to execute, such as start a virtual machine or create a disk volume
  • Parameters: Any additional required or optional parameters for the command

A sample API GET request looks like the following:

https://api.nodilex.com/compute?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Or in a more readable format:

1. https://api.nodilex.com/compute
2. ?command=deployVirtualMachine
3. &serviceOfferingId=1
4. &diskOfferingId=1
5. &templateId=2
6. &zoneId=4
7. &apiKey=miVr6X7u6bN
8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
The first line is the Nodilex API endpoint.

The second line refers to the command you wish to execute. In our example, we are attempting to deploy a fresh new virtual machine. It is preceded by a (?) to separate itself from the API URL.

Lines 3-6 are the parameters for this given command. To see the command and its request parameters, please refer to the appropriate section in the API documentation. Each parameter field-value pair (field=value) is preceded by an ampersand character (&).

Line 7 is the user API Key that uniquely identifies the account. See Signing API Requests (todo url).

Line 8 is the signature hash created to authenticate the user account executing the API command.

Signing Requests

Your requests needs to be signed so we can verify that the caller has been authenticated and authorized to execute the command. Make sure that you have both the API Key and Secret Key provided in your cloud console.

To show how to sign a request, we will re-use the previous example.

http://https://api.nodilex.com/compute?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Breaking this down, we have several distinct parts to this URL.

Base URL: This is the base URL to the API Endpoint.
https://api.nodilex.com/compute

Command String: This part of the query string comprises of the command, its parameters, and the API Key that identifies the account.
?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN

Note

As with all query string parameters of field-value pairs, the "field" component is case insensitive while all “value” values are case sensitive.

Signature: This is the signature of the command string that is generated using a combination of the user’s Secret Key and the HMAC SHA-1 hashing algorithm.
&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Every API request has the format Base URL+Command String+Signature.

To generate the signature.

For each field-value pair (as separated by a ‘&’) in the Command String, URL encode each value so that it can be safely sent via HTTP GET.

Note
Make sure all spaces are encoded as "%20" rather than "+".

Lower case the entire Command String and sort it alphabetically via the field for each field-value pair. The result of this step would look like the following:
apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4

Take the sorted Command String and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method to do this) with the user’s Secret Key. Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP. The final string produced after Base64 encoding should be "Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D".

By reconstructing the final URL in the format Base URL+Command String+Signature, the final URL should look like:

https://api.nodilex.com/compute?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
PHP Code Example
$apikey =  'your api key';
$secretkey = 'your private key';

// Building the query
$args['apikey'] = '$apikey';
$args['command'] = 'listVirtualMachines';
$args['response'] = 'json';
ksort($args);
$query = http_build_query($args);
$query = str_replace('+', '%20', $query);

// generate signature
$hash = @hash_hmac('SHA1', strtolower($query), $secretkey, true);
$base64encoded = base64_encode($hash);
$signature = urlencode($base64encoded);

$finalquery = $query . '&signature=' . $signature;

VirtualMachine

deployVirtualMachine

Creates and automatically starts a virtual machine based on a service offering, disk offering, and template.

Parameter NameDescriptionRequired
serviceofferingidthe ID of the service offering for the virtual machinetrue
templateidthe ID of the template for the virtual machinetrue
zoneidavailability zone for the virtual machinetrue
accountan optional account for the virtual machine. Must be used with domainId.false
affinitygroupidscomma separated list of affinity groups id that are going to be applied to the virtual machine. Mutually exclusive with affinitygroupnames parameterfalse
affinitygroupnamescomma separated list of affinity groups names that are going to be applied to the virtual machine.Mutually exclusive with affinitygroupids parameterfalse
customidan optional field, in case you want to set a custom id to the resource. Allowed to Root Admins onlyfalse
deploymentplannerDeployment planner to use for vm allocation. Available to ROOT admin onlyfalse
detailsused to specify the custom parameters.false
diskofferingidthe ID of the disk offering for the virtual machine. If the template is of ISO format, the diskOfferingId is for the root disk volume. Otherwise this parameter is used to indicate the offering for the data disk volume. If the templateId parameter passed is from a Template object, the diskOfferingId refers to a DATA Disk Volume created. If the templateId parameter passed is from an ISO object, the diskOfferingId refers to a ROOT Disk Volume created.false
displaynamean optional user generated name for the virtual machinefalse
displayvman optional field, whether to the display the vm to the end user or not.false
domainidan optional domainId for the virtual machine. If the account parameter is used, domainId must also be used.false
groupan optional group for the virtual machinefalse
hostiddestination Host ID to deploy the VM to - parameter available for root admin onlyfalse
hypervisorthe hypervisor on which to deploy the virtual machine. The parameter is required and respected only when hypervisor info is not set on the ISO/Template passed to the callfalse
ip6addressthe ipv6 address for default vm's networkfalse
ipaddressthe ip address for default vm's networkfalse
iptonetworklistip to network mapping. Can't be specified with networkIds parameter. Example: iptonetworklist[0].ip=10.10.10.11&iptonetworklist[0].ipv6=fc00:1234:5678::abcd&iptonetworklist[0].networkid=uuid - requests to use ip 10.10.10.11 in network id=uuidfalse
keyboardan optional keyboard device type for the virtual machine. valid value can be one of de,de-ch,es,fi,fr,fr-be,fr-ch,is,it,jp,nl-be,no,pt,uk,usfalse
keypairname of the ssh key pair used to login to the virtual machinefalse
namehost name for the virtual machinefalse
networkidslist of network ids used by virtual machine. Can't be specified with ipToNetworkList parameterfalse
projectidDeploy vm for the projectfalse
rootdisksizeOptional field to resize root disk on deploy. Value is in GB. Only applies to template-based deployments. Analogous to details[0].rootdisksize, which takes precedence over this parameter if both are providedfalse
securitygroupidscomma separated list of security groups id that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupnames parameterfalse
securitygroupnamescomma separated list of security groups names that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupids parameterfalse
sizethe arbitrary size for the DATADISK volume. Mutually exclusive with diskOfferingIdfalse
startvmtrue if start vm after creating; defaulted to true if not specifiedfalse
userdataan optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the request. Using HTTP GET (via querystring), you can send up to 2KB of data after base64 encoding. Using HTTP POST(via POST body), you can send up to 32K of data after base64 encoding.false

startVirtualMachine

Starts a virtual machine.

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue
deploymentplannerDeployment planner to use for vm allocation. Available to ROOT admin onlyfalse
hostiddestination Host ID to deploy the VM to - parameter available for root admin onlyfalse

stopVirtualMachine

Stops a virtual machine.

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue
forcedForce stop the VM (vm is marked as Stopped even when command fails to be send to the backend). The caller knows the VM is stopped.false

rebootVirtualMachine

Reboots a virtual machine.

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue

listVirtualMachines

List the virtual machines owned by the account.

Parameter NameDescriptionRequired
accountlist resources by account. Must be used with the domainId parameter.false
affinitygroupidlist vms by affinity groupfalse
detailscomma separated list of host details requested, value can be a list of [all, group, nics, stats, secgrp, tmpl, servoff, diskoff, iso, volume, min, affgrp]. If no parameter is passed in, the details will be defaulted to allfalse
displayvmlist resources by display flag; only ROOT admin is eligible to pass this parameterfalse
domainidlist only resources belonging to the domain specifiedfalse
forvirtualnetworklist by network type; true if need to list vms using Virtual Network, false otherwisefalse
groupidthe group IDfalse
hostidthe host IDfalse
hostidthe host IDfalse
hypervisorthe target hypervisor for the templatefalse
idthe ID of the virtual machinefalse
idsthe IDs of the virtual machines, mutually exclusive with idfalse
isoidlist vms by isofalse
isrecursivedefaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.false
keypairlist vms by ssh keypair namefalse
keywordList by keywordfalse
listallIf set to false, list only resources belonging to the command's caller; if set to true - list resources that the caller is authorized to see. Default value is falsefalse
namename of the virtual machine (a substring match is made against the parameter value, data for all matching VMs will be returned)false
networkidlist by network idfalse
pagefalse
pagesizefalse
podidthe pod IDfalse
podidthe pod IDfalse
projectidlist objects by projectfalse
serviceofferingidlist by the service offeringfalse
statestate of the virtual machine. Possible values are: Running, Stopped, Present, Destroyed, Expunged. Present is used for the state equal not destroyed.false
storageidthe storage ID where vm's volumes belong tofalse
storageidthe storage ID where vm's volumes belong tofalse
tagsList resources by tags (key/value pairs)false
templateidlist vms by templatefalse
useridthe user ID that created the VM and is under the account that owns the VMfalse
vpcidlist vms by vpcfalse
zoneidthe availability zone IDfalse

resetPasswordForVirtualMachine

Resets the password for virtual machine. The virtual machine must be in a "Stopped" state and the template must already support this feature for this command to take effect. [async]

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue

changeServiceForVirtualMachine

Changes the service offering for a virtual machine. The virtual machine must be in a "Stopped" state for this command to take effect.

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue
serviceofferingidthe service offering ID to apply to the virtual machinetrue
detailsname value pairs of custom parameters for cpu, memory and cpunumber. example details[i].name=valuefalse

Volume

createVolume

Creates a disk volume from a disk offering. This disk volume must still be attached to a virtual machine to make use of it.

Parameter NameDescriptionRequired
namethe name of the disk volumetrue
accountthe account associated with the disk volume. Must be used with the domainId parameter.false
customidan optional field, in case you want to set a custom id to the resource. Allowed to Root Admins onlyfalse
diskofferingidthe ID of the disk offering. Either diskOfferingId or snapshotId must be passed in.false
displayvolumean optional field, whether to display the volume to the end user or not.false
domainidthe domain ID associated with the disk offering. If used with the account parameter returns the disk volume associated with the account for the specified domain.false
maxiopsmax iopsfalse
miniopsmin iopsfalse
projectidthe project associated with the volume. Mutually exclusive with account parameterfalse
sizeArbitrary volume sizefalse
snapshotidthe snapshot ID for the disk volume. Either diskOfferingId or snapshotId must be passed in.false
virtualmachineidthe ID of the virtual machine; to be used with snapshot Id, VM to which the volume gets attached after creationfalse
zoneidthe ID of the availability zonefalse

attachVolume

Attaches a disk volume to a virtual machine.

Parameter NameDescriptionRequired
idthe ID of the disk volumetrue
virtualmachineid the ID of the virtual machinetrue
deviceidthe ID of the device to map the volume to within the guest OS. If no deviceId is passed in, the next available deviceId will be chosen. Possible values for a Linux OS are:* 0 - /dev/xvda* 1 - /dev/xvdb* 2 - /dev/xvdc* 4 - /dev/xvde* 5 - /dev/xvdf* 6 - /dev/xvdg* 7 - /dev/xvdh* 8 - /dev/xvdi* 9 - /dev/xvdjfalse

detachVolume

Detaches a disk volume from a virtual machine.

Parameter NameDescriptionRequired
deviceidthe device ID on the virtual machine where volume is detached fromfalse
idthe ID of the disk volumefalse
virtualmachineidthe ID of the virtual machine where the volume is detached fromfalse

deleteVolume

Deletes a detached disk volume.

Parameter NameDescriptionRequired
idThe ID of the disk volumetrue

SSH

registerSSHKeyPair

Register a public key in a keypair under a certain name

Parameter NameDescriptionRequired
nameName of the keypairtrue
publickeyPublic key material of the keypairtrue
accountan optional account for the ssh key. Must be used with domainId.false
domainidan optional domainId for the ssh key. If the account parameter is used, domainId must also be used.false
projectidan optional project for the ssh keyfalse

createSSHKeyPair

Create a new keypair and returns the private key

Parameter NameDescriptionRequired
nameName of the keypairtrue
accountan optional account for the ssh key. Must be used with domainId.false
domainidan optional domainId for the ssh key. If the account parameter is used, domainId must also be used.false
projectidan optional project for the ssh keyfalse

deleteSSHKeyPair

Deletes a keypair by name

Parameter NameDescriptionRequired
nameName of the keypairtrue
accountthe account associated with the keypair. Must be used with the domainId parameter.false
domainidthe domain ID associated with the keypairfalse
projectidthe project associated with keypairfalse

listSSHKeyPairs

List registered keypairs

Parameter NameDescriptionRequired
accountlist resources by account. Must be used with the domainId parameter.false
domainidlist only resources belonging to the domain specifiedfalse
fingerprintA public key fingerprint to look forfalse
isrecursivedefaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.false
keywordList by keywordfalse
listallIf set to false, list only resources belonging to the command's caller; if set to true - list resources that the caller is authorized to see. Default value is falsefalse
nameA key pair name to look forfalse
pagefalse
pagesizefalse
projectidlist objects by projectfalse

resetSSHKeyForVirtualMachine

Resets the SSH Key for virtual machine. The virtual machine must be in a "Stopped" state. [async]

Parameter NameDescriptionRequired
idThe ID of the virtual machinetrue
keypairname of the ssh key pair used to login to the virtual machinetrue
accountan optional account for the ssh key. Must be used with domainId.false
domainidan optional domainId for the virtual machine. If the account parameter is used, domainId must also be used.false
projectidan optional project for the ssh keyfalse

Template

listTemplates

List all public, private, and privileged templates.

Parameter NameDescriptionRequired
templatefilterpossible values are "featured", "self", "selfexecutable","sharedexecutable","executable", and "community". * featured : templates that have been marked as featured and public. * self : templates that have been registered or created by the calling user. * selfexecutable : same as self, but only returns templates that can be used to deploy a new VM. * sharedexecutable : templates ready to be deployed that have been granted to the calling user by another user. * executable : templates that are owned by the calling user, or public templates, that can be used to deploy a VM. * community : templates that have been marked as public but not featured. * all : all templates (only usable by admins).true
accountlist resources by account. Must be used with the domainId parameter.false
domainidlist only resources belonging to the domain specifiedfalse
hypervisorthe hypervisor for which to restrict the searchfalse
idthe template IDfalse
isrecursivedefaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.false
keywordList by keywordfalse
listallIf set to false, list only resources belonging to the command's caller; if set to true - list resources that the caller is authorized to see. Default value is falsefalse
namethe template namefalse
pagefalse
pagesizefalse
projectidlist objects by projectfalse
showremovedshow removed templates as wellfalse
tagsList resources by tags (key/value pairs)false
zoneidlist templates by zoneIdfalse

Service Offering

listServiceOfferings

Lists all available service offerings.

Parameter NameDescriptionRequired
domainidlist only resources belonging to the domain specifiedfalse
idID of the service offeringfalse
isrecursivedefaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.false
issystemis this a system vm offeringfalse
keywordList by keywordfalse
listallIf set to false, list only resources belonging to the command's caller; if set to true - list resources that the caller is authorized to see. Default value is falsefalse
namename of the service offeringfalse
pagefalse
pagesizefalse
systemvmtypethe system VM type. Possible types are "consoleproxy", "secondarystoragevm" or "domainrouter".false
virtualmachineidthe ID of the virtual machine. Pass this in if you want to see the available service offering that a virtual machine can be changed to.false