This section specifies the representations of the resources which this API operates on. The representations are made up of fields, each with a name and value, encoded using a JSON dictionary. The values may be numeric or string literals, lists, or dictionaries, each of which are represented in the obvious way in JSON.

These representations typically nest. For example, the representation of a VDC will include representations of the Clusters which inhabit it, which in turn include representations of the VMs within each cluster. Two points follow from this:

Retrieving the representation of a VDC gives a comprehensive snapshot of the current state of everything in it using a single GET request. The size of these representations seems, in practice, not excessive.

Many of the models specify that the representation includes a uri field whose value is the URI of the resource being represented. This is present to support URI discovery in nested representations.

Each type of cloud resource has its own Internet Media Type. The media type SHALL conform to the pattern application/vnd.com.sun.cloud.Xxxxxxxx+json, and the specific media type for each resource model is included in square brackets in the corresponding section header.

In the resource model descriptions, fields annotated with [POST] may be included in a POST request, which is normally used to create new resources. Likewise, fields annotated with [PUT] may be included in a PUT request, which is normally used to update properties of existing resources. Fields not so annotated SHOULD NOT be included in the request body of PUT and POST requests, and will be ignored by the server if they are included.

Cloud [application/vnd.com.sun.cloud.Cloud+json]

A Cloud represents a user's view of all accessible resources in the cloud.

A "Cloud" resource model contains the following fields:

Field Name

Type

Occurs

Description

uri

URI

1

A GET against this URI refreshes the client representation of the resources accessible to this user.

locations

Location[]

0..1

The set of locations for VDC deployment that are supported by this service provider.

vdcs

VDC[]

0..1

Virtual data center(s) accessible to this user. Only the name and uri fields MUST be populated by the server.

specification_version

String[]

1

Which version(s) of this specification this server implementation supports.

implementation_version

String

1

Version of the server implementation.

Location [application/vnd.com.sun.cloud.Location+json]

A Location represents a particular geographic or other physical location. VDCs are provisioned within a particular location such that the various included elements may have high bandwidth and secure connectivity.

A "Location" resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name for this location.

uri

URI

1

A GET against this URI refreshes the client representation of this Location resource.

description

String

0..1

Human friendly description of this Location. [POST][PUT]

Virtual Data Center (VDC) [application/vnd.com.sun.cloud.VDC+json]

A VDC represents a user's view of available resources in a single virtual data center. It also provides URIs for acquiring related resource representations, as well as URIs for creating new resources of various types.

A "VDC" resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this virtual data center. [POST][PUT]

uri

URI

1

A GET against this URI refreshes the client representation of this virtual data center.

description

String

0..1

Human friendly description of this VDC. [POST][PUT]

location

URI

0..1

URI of the Location within which resources for this VDC are physically deployed. [POST]

addresses

PublicAddress[]

1

The static public IP addresses which are allocated for use in this VDC. PublicAddress resources that are currently attached will have a URI value in the "vm" field describing to which VM that address is currently attached.

cluster

Cluster

1

The root cluster associated with this VDC.

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

volumes

Volume[]

1

The WebDAV volumes (in the storage service) owned by this user.

vm_templates

URI

1

A GET request against this URI returns an array of available templates (type=application/vnd.com.sun.cloud.VMTemplates+json).

Request Status [application/vnd.com.sun.cloud.Status+json]

A status represents a report on the progress of a request for a change in the state of the cloud. Such requests receive an HTTP status code of "202 Accepted", with the response body being a Status representation.

This is designed to be used by applications to poll the server to track the progress of a request; thus, server implementations SHOULD anticipate this activity and make such polling reasonably lightweight.

A status resource model contains the following fields:

Field Name

Type

Occurs

Description

op

String

1

Identifies the nature of the request whose status this represents. The possible values are described in the specifications of the individual requests.

progress

Integer in the range 0-100, inclusive

1

Represents the progress towards completion of the request. A value of 100 indicates that the request has completed. There is no requirement that implementations be able to predict the latency of requests; it should not be surprising if, during the lifetime of a request, the progress value remains at 0 until it changes to 100 upon request completion.

target_uri

URI

1

Identifies the resource upon which the request is acting. Specific semantics depend on the details of the request, and are described fully in the specifications of the individual requests.

status_uri

URI

1

Identifies this status resource and may be used to retrieve an up-to-date status report.

status

Integer

1

HTTP status code describing the result of the completed operation. Typical values would be 200, 201, and various error codes. This value is only meaningful if the value of the "progress" field is 100.

message

String

1

Brief message describing the completed operation (if successful) or an error message (if not successful). This value is only meaningful if the value of the "progress" field is 100.

Public Address [application/vnd.com.sun.cloud.PublicAddress+json]

A public address represents a static, publicly accessible Internet Protocol (IP) address, which can be attached to a particular VM via an interface. The fact that this address is static means it is suitable for registration with the Domain Name Service (DNS) environment for your application domain. Typically, the VM that a public address is attached to will be a firewall appliance, but this is not required by the Cloud API itself.

A public address resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this Public Address (unique within owning VDC). [POST][PUT]

uri

URI

1

URI by which this public address may be addressed as a standalone resource.

description

String

0..1

Human friendly description of this Public Address. [POST][PUT]

vdc

URI

1

URI of the VDC this PublicAddress belongs to.

dns

String[]

1

List of DNS server IP addresses to be used for connecting out through this Internet connection. [POST][PUT]

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

vm

URI

0..1

URI of the VM to which this address is attached, if any.

Cluster [application/vnd.com.sun.cloud.Cluster+json]

A cluster represents a grouping of VM and VNet resources, segregated for purposes of grouping by common functionality, shared access control, or other purposes. Each VDC contains, by definition, one root cluster, which may in turn contain other clusters; the effect is that of a filesystem-like hierarchy of clusters.

A cluster resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this cluster, unique within the owning VDC. [POST][PUT]

uri

URI

1

URI by which this cluster may be addressed as a standalone resource.

description

String

0..1

Human friendly description of this Cluster. [POST][PUT]

vdc

URI

1

URI of the VDC this Cluster belongs to.

parent

URI

0..1

URI of the parent Cluster for this Cluster (if this is not the root cluster of a VDC).

from_cluster

URI

0..1

On a Create Cluster request type, the URI of an existing cluster to initialize default values from. [POST]

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

vnets

VNet[]

0..1

The collection of virtual private networks associated with this Cluster.

vms

VM[]

0..1

The collection of virtual machines associated with this cluster.

controllers

{}

0..1

Hash of URIs which may be used to request state changes in the cluster via POST requests (see next table), keyed by the type of state change being requested.

clusters

Cluster[]

0..1

Collection of Clusters which are logically contained in this cluster.

Some of the "control" URIs may or may not be accessible based on the state of the cluster, and may not appear in representations of it when not usable. For convenience, these are grouped into the "controllers" list field, in which zero or more of the following URIs (keyed by the change type) will be included in a representation provided by the server.

Change Type

Operation Requested

start

Start up all the VMs in this cluster, in ascending order based on the boot_order value of each VM.

stop

Shut down all the VMs this cluster, in descending order based on the boot_order value of each VM.

Volume [application/vnd.com.sun.cloud.Volume+json]

A Volume represents a remote WebDAV volume that may be accessed by the same credentials used to access this information. Such volumes are global to the calling user, and are therefore enumerated in the containing VDC.

A Volume resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this volume (unique within the owning VDC). [POST][PUT]

uri

URI

1

GET, PUT, and DELETE operations may be used to retrieve, update, or delete this volume.

description

String

0..1

Human friendly description of this Volume. [POST][PUT]

vdc

URI

1

URI of the VDC this Volume belongs to.

webdav

URI

1

The URI for use in any WebDAV operations.

created

Timestamp

1

Date and time when this volume was created.

snapshots

Snapshot[]

0..1

Collection of snapshots associated with this volume.

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Snapshot [application/vnd.com.sun.cloud.Snapshot+json]

A Snapshot represents a point-in-time representation of the contents of a Volume.

A Snapshot resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this snapshot, unique within the owning Volume. [POST]

uri

URI

1

GET, PUT, and DELETE operations may be used to retrieve, update, or delete this snapshot.

description

String

0..1

Human friendly description of this Snapshot. [POST][PUT]

volume

URI

1

URI of the Volume this Snapshot belongs to.

created

Timestamp

1

Date and time when this snapshot was created.

clone

URI

0..1

A POST to this URI is a request to clone this snapshot into a new volume with a name included in the request body.

rollback

URI

0..1

A POST to ths URI is a request to revert the owning volume to the contents as of when this snapshot was created.

Virtual Machine (VM) [application/vnd.com.sun.cloud.VM+json]

A VM represents a virtual computer that is associated with a cluster.

A VM data model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this VM, unique within the owning Cluster. [POST][PUT]

uri

URI

1

GET, PUT, and DELETE may be used to retrieve representations of the VM, to update it, and to delete it, respectively.

description

String

0..1

Human friendly description of this VM. [POST][PUT]

cluster

URI

1

URI of the Cluster this VM belongs to.

run_status

String

0..1

Current running status of this virtual machine (read only). Valid values for this field are "STOPPED", "STARTING", "STARTED", "SLEEPING", "ASLEEP", "WAKING", and "STOPPING". Initial run_status of a newly created VM is "STOPPED".

updated

Boolean

1

A value of true means that a change has been made to the VM resource, which will not take effect until the VM has been rebooted.

last_boot

Timestamp

1

Date when this VM was most recently booted.

from_template

String

0..1

On a Create VM request type, the URI of an existing VM template to initialize default values from. [POST]

from_vm

String

0..1

On a Create VM request type, the URI of an existing VM to initialize default values from. [POST]

hostname

String

0..1

Fully qualified (?) host name of this virtual machine.

os

String

0..1

Operating system running on the VM. FIXME - enumerate the legal values. [POST]

cpu

Integer

0..1

CPU speed in Mhz. [POST]

memory

Integer

0..1

Main memory size in MB. [POST]

boot_disk

Integer

0..1

Boot disk space to allocate in GB. [POST]

data_disk

Integer

0..1

Data disk space to allocate in GB. [POST]

temp_disk

Integer

0..1

Temporary disk space to allocate in GB. [POST]

boot_order

Integer

0..1

Sort ordering value for start cluster and stop cluster operations. When a cluster is started, VMs with the same boot_order value will be started in an undefined sequence, but the service will ensure that all VMs with a particular boot_order value will have been started before starting VMs with a higher boot_order value. The sequence is reversed for a stop cluster operation. VMs with no boot_order value will be assumed to have a boot_order of the maximum integer value, so they will be started last and stopped first. [POST][PUT]

params

{ }

0..1

Configuration parameters for this VM, keyed by parameter name. The list of system defined configuration parameters is TBD, but one of them will be "user_params", whose value is a hash of arbitrary user defined configuration parameters. [POST][PUT]

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

back_up

URI

1

A POST of a Backup representation to this URI requests creation of a new Backup.

attach

URI

1

A POST of a PublicAddress representation to this URI requests connection to a Public Address. Or, a POST of a VNet representation to this URI requests connection to a VNet.

detach

URI

1

A POST of a PublicAddress representation to this URI requests disconnection from a Public Address. Or, a POST of a VNet representation to this URI reequests disconnection from a VNet.

backups

Backup[]

0..1

Backup snapshots from this virtual machine.

interfaces

Interface[]

1

Network interfaces associated with this virtual machine. These are created automatically when VNets or Public Addresses are associated with VM.[POST]

controllers

{}

0..1

Hash of URIs which may be used to request state changes in the VM via POST requests (see next table), keyed by the type of state change being requested.

Some of the "control" URIs, such as those identified in the "attach" and "detach" fields, are in principle always accessible and thus appear as first-class values in the representation of a VM. Others may or may not be accessible based on the state of the VM, and may not appear in representations of it when not accessible. For convenience, these are grouped into the "controllers" list field, in which zero or more of the following URIs (keyed by the change type) will be included in a representation provided by the server.

Change Type

Operation Requested

Initial State

Intermediate State

Final State

start

Start up a VM.

STOPPED

STARTING

STARTED

stop

Shut down a running VM.

STARTED

STOPPING

STOPPED

reboot

Reboot a running VM.

STARTED

STOPPING -> STOPPED -> STARTING

STARTED

hibernate

Put a running VM to sleep.

STARTED

SLEEPING

ASLEEP

resume

Wake up a hibernated VM.

ASLEEP

WAKING

STARTED

Backup [application/vnd.com.sun.cloud.Backup+json]

A backup represents a snapshot that was taken of a specific virtual machine.

A backup resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this backup, unique within owning VM. [POST][PUT]

uri

URI

1

GET, PUT, and DELETE may be used to retrieve representations of the Backup, to update it, and to delete it, respectively.

description

String

0..1

Human friendly description of this Backup. [POST][PUT]

type

String

0..1

Type of this backup (service provider default if not specified). [POST]

created

DateTime

1

Timestamp when this backup was created.

restore

URI

1

URI that will accept a POST to restore the state of the associated VM to this Backup.

vm

URI

1

URI of the VM that this Backup was captured for.

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Virtual Network (VNet) [application/vnd.com.sun.cloud.VNet+json]

A VNet represents a virtual private network to which an interface associated with a VM may be attached. VNets may connect VMs within a Cluster, or they may connect VMs from different clusters together to provide a private communications path.

A VNet is logically contained within a cluster, but this relationship only exists for administrative purposes and does not affect the operations available on it.

A VNet resource model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this VNet, unique within the owning Cluster. [POST][PUT]

uri

URI

1

URI that may be used to access this VNet as a standalone resource.

description

String

0..1

Human friendly description of this 'VNet. [POST][PUT]

cluster

URI

1

URI of the Cluster this VNet belongs to.

netmask

String

1

Default network mask for interfaces connected to this VNet.

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Interface [application/vnd.com.sun.cloud.Interface+json]

An interface represents a network interface card (nic), associated with a specific VM, that documents an IP connection (from this VM) either to a VNet (virtual private network) or to a public address (a static public IP address accessible from the Internet). For the latter scenario, the VM will typically implement firewall and/or load balancing functionality, but this is not required by the API.

Interface instances are created, modified, and removed as a side effect of other operations. Therefore, they do not possess a URI of their own, and support no operations against themselves directly.

A interface resource model contains the following fields:

Field Name

Type

Occurs

Description

vnet

URI

0..1

The URI of the VNet instance, if this interface is attached to one. At most one of vnet or public address must be defined.

public_address

URI

0..1

The URI of the public address instance, if this interface is attached to one. At most one of vnet or public address must be defined.

nic

String

1

Name of the network interface connector as seen by the host operating system.

mac_address

String

1

MAC address of this network interface.

ip_address

String

1

IP address of this network interface. If the interface is connected to a Public Address, will be a duplicate of its ip_address field.

A VMTemplate represents a preconfigured virtual machine image that may be "cloned" in a Create Virtual Machine request, by specifying the URI of a particular template as the value of the from_template field.

A VMTemplate data model contains the following fields:

Field Name

Type

Occurs

Description

name

String

1

Logical name of this VMTemplate.

uri

URI

1

URI to reference this template in a Create Virtual Machine request.

description

String

0..1

Human friendly description of this virtual machine template.

os

String

0..1

Operating system running on the VM. FIXME - enumerate the legal values.

cpu

Integer

0..1

CPU speed in Mhz.

memory

Integer

0..1

Main memory size in MB.

boot_disk

Integer

0..1

Boot disk space to allocate in GB.

data_disk

Integer

0..1

Data disk space to allocate in GB.

temp_disk

Integer

0..1

Temporary disk space to allocate in GB.

params

{ }

0..1

Configuration parameters for this VM, keyed by parameter name. The list of system defined configuration parameters is TBD, but one of them will be "user_params", whose value is a hash of arbitrary user defined configuration parameters.

tags

[ ]

0..1

Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud.