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

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.

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.

NoteMake 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:

VirtualMachine

deployVirtualMachine

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

Parameter Name

Description

Required

serviceofferingid

the ID of the service offering for the virtual machine

true

templateid

the ID of the template for the virtual machine

true

zoneid

availability zone for the virtual machine

true

account

an optional account for the virtual machine. Must be used with domainId.

false

affinitygroupids

comma separated list of affinity groups id that are going to be applied to the virtual machine. Mutually exclusive with affinitygroupnames parameter

false

affinitygroupnames

comma separated list of affinity groups names that are going to be applied to the virtual machine.Mutually exclusive with affinitygroupids parameter

false

customid

an optional field, in case you want to set a custom id to the resource. Allowed to Root Admins only

false

deploymentplanner

Deployment planner to use for vm allocation. Available to ROOT admin only

false

details

used to specify the custom parameters.

false

diskofferingid

the 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

displayname

an optional user generated name for the virtual machine

false

displayvm

an optional field, whether to the display the vm to the end user or not.

false

domainid

an optional domainId for the virtual machine. If the account parameter is used, domainId must also be used.

false

group

an optional group for the virtual machine

false

hostid

destination Host ID to deploy the VM to - parameter available for root admin only

false

hypervisor

the 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 call

an 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,us

false

keypair

name of the ssh key pair used to login to the virtual machine

false

name

host name for the virtual machine

false

networkids

list of network ids used by virtual machine. Can't be specified with ipToNetworkList parameter

false

projectid

Deploy vm for the project

false

rootdisksize

Optional 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 provided

false

securitygroupids

comma 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 parameter

false

securitygroupnames

comma 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 parameter

false

size

the arbitrary size for the DATADISK volume. Mutually exclusive with diskOfferingId

false

startvm

true if start vm after creating; defaulted to true if not specified

false

userdata

an 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 Name

Description

Required

id

The ID of the virtual machine

true

deploymentplanner

Deployment planner to use for vm allocation. Available to ROOT admin only

false

hostid

destination Host ID to deploy the VM to - parameter available for root admin only

false

stopVirtualMachine

Stops a virtual machine.

Parameter Name

Description

Required

id

The ID of the virtual machine

true

forced

Force 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 Name

Description

Required

id

The ID of the virtual machine

true

listVirtualMachines

List the virtual machines owned by the account.

Parameter Name

Description

Required

account

list resources by account. Must be used with the domainId parameter.

false

affinitygroupid

list vms by affinity group

false

details

comma 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 all

false

displayvm

list resources by display flag; only ROOT admin is eligible to pass this parameter

an optional domainId for the ssh key. If the account parameter is used, domainId must also be used.

false

projectid

an optional project for the ssh key

false

createSSHKeyPair

Create a new keypair and returns the private key

Parameter Name

Description

Required

name

Name of the keypair

true

account

an optional account for the ssh key. Must be used with domainId.

false

domainid

an optional domainId for the ssh key. If the account parameter is used, domainId must also be used.

false

projectid

an optional project for the ssh key

false

deleteSSHKeyPair

Deletes a keypair by name

Parameter Name

Description

Required

name

Name of the keypair

true

account

the account associated with the keypair. Must be used with the domainId parameter.

false

domainid

the domain ID associated with the keypair

false

projectid

the project associated with keypair

false

listSSHKeyPairs

List registered keypairs

Parameter Name

Description

Required

account

list resources by account. Must be used with the domainId parameter.

false

domainid

list only resources belonging to the domain specified

false

fingerprint

A public key fingerprint to look for

false

isrecursive

defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.

false

keyword

List by keyword

false

listall

If 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 false

false

name

A key pair name to look for

false

page

false

pagesize

false

projectid

list objects by project

false

resetSSHKeyForVirtualMachine

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

Parameter Name

Description

Required

id

The ID of the virtual machine

true

keypair

name of the ssh key pair used to login to the virtual machine

true

account

an optional account for the ssh key. Must be used with domainId.

false

domainid

an optional domainId for the virtual machine. If the account parameter is used, domainId must also be used.

false

projectid

an optional project for the ssh key

false

Template

listTemplates

List all public, private, and privileged templates.

Parameter Name

Description

Required

templatefilter

possible 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

account

list resources by account. Must be used with the domainId parameter.

false

domainid

list only resources belonging to the domain specified

false

hypervisor

the hypervisor for which to restrict the search

false

id

the template ID

false

isrecursive

defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.

false

keyword

List by keyword

false

listall

If 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 false

false

name

the template name

false

page

false

pagesize

false

projectid

list objects by project

false

showremoved

show removed templates as well

false

tags

List resources by tags (key/value pairs)

false

zoneid

list templates by zoneId

false

Service Offering

listServiceOfferings

Lists all available service offerings.

Parameter Name

Description

Required

domainid

list only resources belonging to the domain specified

false

id

ID of the service offering

false

isrecursive

defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.

false

issystem

is this a system vm offering

false

keyword

List by keyword

false

listall

If 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 false

false

name

name of the service offering

false

page

false

pagesize

false

systemvmtype

the system VM type. Possible types are "consoleproxy", "secondarystoragevm" or "domainrouter".

false

virtualmachineid

the 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.