Introduction¶

Welcome to the CloudsFor API documentation.

The CloudsFor API allows you to manage VMs and resources within the cloud in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

All of the functionality that you are familiar with in the CloudsFor control panel is also available through the API, allowing you to script the complex actions that your situation requires.

The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.

Requests¶

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Method	Usage
GET	For simple retrieval of information about your account, VMs, or environment, you should use the GET method. The information you request will be returned to you as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the objects you are querying.
DELETE	To destroy a resource and remove it from your account and environment, the DELETE method should be used. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource’s availability prior to issuing a delete command, the final state will be the same regardless of its existence.
PUT	To update the information about a resource in your account, the PUT method is available. Like the DELETE Method, the PUT method is idempotent. It sets the state of the target using the provided values, regardless of their current values. Requests using the PUT method do not need to check the current attributes of the object.
POST	To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.
HEAD	Finally, to retrieve metadata information, you should use the HEAD method to get the headers. This returns only the header of what would be returned with an associated GET request. Response headers contain some useful information about your API access and the results that are available for your request.

HTTP Statuses¶

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

EXAMPLE ERROR RESPONSE:

HTTP/1.1 403 Forbidden
{
  "id":       "forbidden",
  "message":  "You do not have access for the attempted action."
}

Responses¶

When a request is successful, a response body will typically be sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body.

Inside of this JSON object, the resource root that was the target of the request will be set as the key. This will be the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed.

For example, if you send a GET request to /api/v1/vms/$VM_ID you will get back an object with a key called “vm”. However, if you send the GET request to the general collection at /api/v1/vms, you will get back an object with a key called “vms”.

The value of these keys will generally be a JSON object for a request on a single object and an array of objects for a request on a collection of objects.

Response for a Single Object:

{
    "vm": {
        "name": "example.com"
       . . .
    }
}

Response for an Object Collection:

{
    "vms": [
        {
            "name": "example.com"
            . . .
        },
        {
            "name": "second.com"
            . . .
        }
    ]
}

Meta¶

In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.

The meta object contains a total key that is set to the total number of objects returned by the request. This has implications on the links object and pagination.

The meta object will only be displayed when it has a value. Currently, the meta object will have a value when a request is made on a collection (like VMs or domains).

Sample Meta Object:

{
    . . .
    "meta": {
        "total": 43
    }
    . . .
}

Curl Examples¶

Throughout this document, some example API requests will be given using the curl command. This will allow us to demonstrate the various endpoints in a simple, textual format.

The names of account-specific references (like VM IDs, for instance) will be represented by variables. For instance, a VM ID may be represented by a variable called $VM_ID. You can set the associated variables in your environment if you wish to use the examples without modification.

You may also wish to set some other variables now or as you go along. For example, you may wish to set the VM_ID variable to one of your VM IDs since this will be used frequently in the API.

If you are following along, make sure you use a VM ID that you control for so that your commands will execute correctly.

If you need access to the headers of a response through curl, you can pass the -i flag to display the header information along with the body. If you are only interested in the header, you can instead pass the -I flag, which will exclude the response body entirely.

Set and Export a Variable:

export VM_ID=5609f1ee1b0c4d2da622737b5ca25e6c

Parameters¶

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

Pass Parameters as a JSON Object:

curl -u "<username:password>" \
     -H "Content-Type: application/json" \
     -d '{"name": "example.com", "ip_address": "127.0.0.1"}' \
     -X POST "https://cloudsfor.com/api/v1/domains"