The ComputeNext API has been designed to allow you to find, access and control your cloud computing resources. But, because we are a federated cloud, we have some features of our API that might be a little different to what you are used to. When we sat down to originally design the ComputeNext API, we were obviously influenced by what had come before. In particular, we took a good look at the AWS EC2 and OpenStack Compute interfaces. We also wanted to include the concept of workloads from the start, so in our API, every virtual machine or volume storage instance is part of a workload. Activating resources in ComputeNext consists of defining a workload, adding the resources you want to that workload, and then activating the workload. When a workload is activated, it becomes a transaction. The other thing to note about the ComputweNext API is that it is mostly asynchronous. In standard cloud computing API’s, the cloud provider has the benefit of full control over their resources. But in a federated cloud, we are aggregating resources from multiple cloud providers. So, we need to be prepared for additional steps in the process – for example, the user asks us for status, then we ask the provider for status, then the status returns from the provider, we store the status in our database, and then the user retrieves the status from our database. That way, the user is not blocked by the additional steps required to talk to a federated provider. But it might take a bit of getting used to if you are expecting synchronous behavior.

The ComputeNext API is a REST API and can be tested using curl. We support both HTTP and HTTPS. Authentication is done using standard Basic authentication, where you supply a username and password as part of each request. Of course, you would not want to use the same username and password that you sign-in to the ComputeNext website with, so we allow you to generate “API Access Keys” – which you use as the username and password when accessing the ComputeNext API.

To get your API Access Keys –

1. Sign-in to ComputeNext.com
2. Contact [email protected] for an API Key
3. Support will reply to you with an access and secret key
4. Copy your access key and secret key from the email.

Using API Keys is very flexible, you can manage access to your resources from different sources with different keys, and if you decide you no longer want access from that source you can disable or delete that key without affecting your other applications.
There are two parts to an API Access Key – the identifier part, and the secret part. The identifier part is just used to identify the key, and it is not secret (although it’s a good idea to keep it somewhat restricted), and this corresponds to the Basic authentication username. The secret part is – as its name suggests, the secret! – and this corresponds to the Basic authentication password. Basic authentication carries the username and password “on the wire” in clear, so it’s recommended to use HTTPS if you can which will encrypt this.
Note: Do not confuse our API Keys with the public/private key pairs that you can use to actually access your virtual machine instances when they are activated. These are two different things.
Once you have got your API Keys you can try accessing the ComputeNext API. One of the simplest requests is to list something –

>curl -i http://cws.computenext.com/api/instance -u <apikey>:<apisec>
HTTP/1.1 200 OK
Content-Length: 2
Content-Type: text/html; charset=utf-8
Server: Microsoft-IIS/7.5
X-Powered-By: Express
X-Powered-By: ASP.NET
X-Powered-By: ARR/2.5
X-Powered-By: ASP.NET
Date: Thu, 19 Dec 2013 00:25:27 GMT

[
{
"instanceId": "805346e2-39e5-4ec6-9d3d-02dca7ca38fc",
"created": "2013-12-19T09:17:58.268Z",
"updated": "2013-12-19T09:17:58.268Z",
"ownerId": "0c91e10a-0a12-494d-bd8d-baad37183734",
"resourceUri": "kp/hpcloud/nova/standard",
"resourceType": "kp",
"provider": "hpcloud",
"region": "nova",
"attributes": {
"providerInstanceId": "805346e2-39e5-4ec6-9d3d-02dca7ca38fc",
"publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDHlXxlL08TIRTfFObCD9XXXuCoxMGaQ9zYVboL7fvV4VeW
PTy/qkBtNdh5IzqpC07M+XEJaJ3IBkvo/ehMIiNzotZOZgRgJdiJoQCkdb0TDAvDyDWxjdCfVEajfSHO004MxaqWNY1fPHP
cZBNTVleTB9TIeKqRzlN9z8nADkEAPQ== n",
"privateKey": "-----BEGIN RSA PRIVATE KEY-----nMIICXAIBAAKBgQDHlXxlL08TIRTfFObCD9XXXuCoxMGaQ9
zYVboL7fvV4VeWPTy/nqkBtNdh5IzqpC07M+XEJaJ3IBkvo/ehMIiNzotZOZgRgJdiJoQCkdb0TDAvDyDWxnjdCfVEajf
SHO004MxaqWNY1fPHPcZBNTVleTB9TIeKqRzlN9z8nADkEAPQIDAQABnAoGAdQYuoTnDGMlN7pvXzjPww86K1gpAJo7iACsL
4pDRGBCABcS0SQGvsxlea3D/npTzPIJql78lasn0Wp2+xdGqT8+FXaDhR6a+yJEY0ZmRaivVcGnhdTLxzrtQ0/
FG8ndslK0gSvjgHRm2uYyp0ds6MexEuRipivRkpDzeIwYikhBYECQQDr16XzV957wtaonC4qhgpfvgm1Y96
KGruy09cwT0u7GlldZfq7KwtgnNITtTkCMHe4qiczyjPrSeoKwnUfwA0+bhAkEA2KR7/Nlhrs12o6cl
ItOyoF0F9GWhVVPCu1LxcQtK5WvTnjFIQNRynHcsYZvjfOIFDoyDTC084woAn3xrJ85iw3QJAKGT6RpDBSZ9YltXL
O9ibX2mOgxN/nIeRqJKCJAMg7H4Z2lZyOIap3zVdAgUjK43To6x5JHS4qc8yJ/9s694VT4QJBAIIvnvg6BN3F
LKStJK0jVfLdfj0+Br0TOc+wL+OlcxuI9PMsIhIno4LbEsGJY1hNnopSqnCgj2z34ac1tgBtIrBMUCQGAdWIA
zmCBKAUAilFYLckG7jgex/nK7lBZuEMsQ7+4+nBDbj/ElDhvOo9kKM8AKpA/3wLC1UfDw14fkpQAS
iJok=n-----END RSA PRIVATE KEY-----n",
"keyFingerprint": "b4:5b:95:29:6e:49:f2:79:88:63:a6:95:db:79:56:8c",
"instanceStatus": "created",
"transientStatus": false
},
"attributeTimestamps": {
"instanceStatus": "2013-12-19T09:17:58.265Z"
},
"metadata": {
"name": "MyKeyPair",
"transactionId": "3a765a62-c2fa-412f-8675-6fbd6782dcf0"
},
"parameters": {
"kp_providerResourceId": "standard",
"zone": "nova"
}
},
{
"instanceId": "9cb7487e-824c-4a03-8de0-235a12e8c0c9",
"created": "2013-12-19T09:17:59.588Z",
"updated": "2013-12-19T09:18:01.320Z",
"ownerId": "0c91e10a-0a12-494d-bd8d-baad37183734",
"resourceUri": "sg/hpcloud/nova/standard",
"resourceType": "sg",
"provider": "hpcloud",
"region": "nova",
"providerResourceId": "standard",
"attributes": {
"providerInstanceId": 568597,
"instanceStatus": "created",
"transientStatus": false,
"rules": [
{
"protocol": "tcp",
"from-port": 22,
"to-port": 22,
"cidr-ip": [
"0.0.0.0/0"
],
"id": 414383,
"added": true
},
{
"protocol": "tcp",
"from-port": 3389,
"to-port": 3389,
"cidr-ip": [
"0.0.0.0/0"
],
"id": 414385,
"added": true
},
{
"protocol": "icmp",
"from-port": -1,
"to-port": -1,
"cidr-ip": [
"0.0.0.0/0"
],
"id": 414387,
"added": true
}
] },
"attributeTimestamps": {
"instanceStatus": "2013-12-19T09:18:01.299Z",
"rules": "2013-12-19T09:18:01.300Z"
},
"metadata": {
"name": "MyDefault",
"transactionId": "3a765a62-c2fa-412f-8675-6fbd6782dcf0"
},
"parameters": {
"sg_providerResourceId": "standard",
"zone": "nova"
}
},
{
"instanceId": "b6caea2c-3f92-4833-b4ae-e33ea67571d9",
"created": "2013-12-19T09:18:04.673Z",
"updated": "2013-12-19T09:22:59.478Z",
"ownerId": "0c91e10a-0a12-494d-bd8d-baad37183734",
"resourceUri": "vm/hpcloud/nova/standard.xsmall",
"resourceType": "vm",
"provider": "hpcloud",
"region": "nova",
"providerResourceId": "Standard.xsmall",
"attributes": {
"providerInstanceId": 2711357,
"password": "ZBASeNQQaq79VXMp",
"instanceStatus": "deleted",
"transientStatus": false,
"privateIpAddress": "10.2.246.157",
"publicIpAddress": "15.185.244.53"
},
"attributeTimestamps": {
"password": "2013-12-19T09:19:01.983Z",
"instanceStatus": "2013-12-19T09:22:59.456Z",
"privateIpAddress": "2013-12-19T09:19:01.984Z",
"publicIpAddress": "2013-12-19T09:19:01.985Z"
},
"metadata": {
"name": "CNWFFA26_E88F_43A9_ABE6_94BFF21DA885",
"description": "HPCloud xSmall VM with Fedora 16 Server Nova",
"transactionId": "af678a28-d960-470c-b2b4-a0a8532242bd",
"originalWorkloadId": "14538a67-e35a-4e9b-835d-afa2c0f84dd1"
},
"parameters": {
"imageUri": "image/hpcloud/nova/ami-000011a5",
"keyPairId": "805346e2-39e5-4ec6-9d3d-02dca7ca38fc",
"securityGroupIds": [
"9cb7487e-824c-4a03-8de0-235a12e8c0c9"
],
"vm_providerResourceId": "Standard.xsmall",
"zone": "nova",
"cpuCount": "1",
"cpuSpeed": "1.2",
"localStorage": "30",
"ram": "1",
"username": "root",
"image_providerResourceId": "ami-000011a5",
"keyPairId_providerInstanceId": "805346e2-39e5-4ec6-9d3d-02dca7ca38fc",
"securityGroupIds_providerInstanceId": [
568597
] }
}

This returns all the details pertaining to all the instances belonging to the user. Note that output from our API is always in JSON format.
The ComputeNext API is organized according to the different resource types, and also includes workloads and transactions.
The ComputeNext API has the following basic resource types –
Key Pairs: These are the key pairs (one public key plus one private key) that are used to access your virtual machine instance. Generally, Linux machines use key pairs for access over SSH, while Windows machines use a username/password over RDP.
Security Groups: These are security groups in which you can place your virtual machine instances so that access to them is restricted to certain ports. Similar to firewall rules.
Key Pairs and Security Groups can be created independently of a workload, but can be used within a workload.
Virtual Machines: These are your compute instances. They are always created as part of a workload, and are always in a workload. Virtual machines are created with a specific image and instance type.
Volume Storage: This is the storage that is attached to your virtual machine instance. A virtual machine can have multiple volume stores attached. Volume storage is always created as part of a workload, and is always in a workload.
You build a workload by –
1. Define the workload: Give the workload a name.

2. Add Resources to Workload: Add Virtual Machine and Volume Storage resources to it. You can include (previously defined) Key Pairs and Security Groups, or you can specify new names for Key Pairs and Security Groups that will be created as part of the workload activation.

3. Validate the workload: This checks that the resources you have added are compatible. The workload API (/workloads) is used to manage the workload definition. But to activate and control the transaction, you will use the transaction API (/transactions). The workload is all about resource definitions – building and editing the workload – and the transaction is all about the instances that are created from the workload. You will get the status of all the resource instances using the transactions API.

4. Activate the workload: This is done using the transaction API. When a workload is activated, this creates a transaction that is associated with the workload. Once the workload has a transaction associated with it, the workload can no longer be modified. However, you can clone the workload definition using the workload API, so that allows you to effectively use the same definition of the workload again in a new transaction.

5. Monitor the transaction. If you want to know the status of your instances you will use the transaction API to “retrieve transaction detail”. This returns the status of all instances in the transaction in one go. Beware though, this is asynchronous. When you call this method, it returns the status immediately from the ComputeNext database, but it kicks off status requests to the various providers – and there may be more than one – to refresh the resource instance status. So it may be that you get “stale” status the first time you call this method. Make sure to check when the status was updated.
The transaction API is designed to be quite lightweight and return instance status that changes frequently. The workload API returns full details about what your resources actually are. One is designed to be called fairly frequently, and the other should need to be called less frequently, because it contains information that doesn’t change. If you design your application accordingly you should get better performance.
The transaction API (/transactions) can be used to control the behavior of the transaction as a whole – start/stop/delete transaction for example. There are also the /virtualmachines or /volumes APIs that can be used to control specific resource instances within the transaction – stop or start a particular instance, for example. There is also one “helper” method which can create a virtual machine in a single operation – this will actually define a workload, add the virtual machine to it, and activate the workload.