Creating, Starting, Stopping and Rebooting Instances

Creating Instances

You can create instances by POSTing to /api/clouds/<cloud_id>/instances

headers = {"X-Scalarium-Token" => "XXXXX",
  "Accept" => "application/vnd.scalarium-v1+json",
  "Content-Type"=>"application/json"}

RestClient.post('https://manage.scalarium.com/api/clouds/XXXXX/instances",
                        JSON.dump(:nickname => 'Mr. Coffee',
                           :availability_zone => 'eu-west-1a',
                           :instance_type => 'c1.medium',
                           :roles => ["0721a85e9ac99c43f8c9cc355fe82340"]),
                        headers)

Accepted attributes in the POST body (encoded as JSON hash) are:

• nickname: Name for the instance, leave blank to have one automatically generated based on the naming scheme you've chosen for the cloud.
• availability_zone: Must be one of the availability zones in your cloud's regions, e.g. eu-west-1a or us-east-1b.
• instance_type: One of the available instance type. The valid name conforms with Amazon's API naming scheme, e.g. m1.small, c1.medium.
• roles: An array containing a list of roles, identified by their ID, which you can fetch from a cloud's roles listing. Must at least contain one valid role.

If validation fails, the API will return HTTP status code 412 with the errors included in the body, like so:

{
  "errors": ["Can't create instance without at least one role"]
}

If you are using RestClient, you get an exception in case of a 412 HTTP response. To evaluate the response body, you need to catch the exception, e.g.:

headers = {"X-Scalarium-Token" => "XXXXX",
    "Accept" => "application/vnd.scalarium-v1+json",
    "Content-Type"=>"application/json"}
begin
  RestClient.post('https://manage.scalarium.com/api/clouds/XXXXX/instances",
                        JSON.dump(:nickname => 'Mr. Coffee',
                           :availability_zone => 'eu-west-1a',
                           :instance_type => 'c1.medium',
                           :roles => ["0721a85e9ac99c43f8c9cc355fe82340"]),
                        headers)
rescue => e
  e.response
end

If the instance was successfully created, the response will include the HTTP location of the new instance and its ID in the response body:

{
  "id":"afcea12f14cbcffe1ec61cf12cd543e4"
}

Starting, Stopping, Rebooting

These activities are as simple as posting to the corresponding actions, /api/clouds/<cloud_id>/instances/<instance_id>/start, /api/clouds/<cloud_id>/instances/<instance_id>/reboot and /api/clouds/<cloud_id>/instances/<instance_id>/stop respectively. The request doesn't need a body.

RestClient.post('https://manage.scalarium.com/api/clouds/58241eff9ef684d91b459adf7deb7899/instances/fcadba9b3002d2b3700dd0c70404b843/stop',
   '', headers)

The response will send status code 202 if the request was accepted and include the updated data of the instance. You can keep polling for the instance's details after you've started or stopped an instance to find out the currrent status, as the processing of your request is done through a background task.

If the instance is in a state that doesn't allow the desired activity, the API will return a 412 and the appropriate error message in the response body.

Deleting an Instance

To delete an instance, send a DELETE request to the the instances URI:

 RestClient.delete("https://manage.scalarium.com/api/clouds/58241eff9ef684d91b459adf7deb7899/instances/fcadba9b3002d2b3700dd0c70404b843/")

The instance needs to be stopped, otherwise the API will return an error.