Jump to Page:

The APIs for the Sun Cloud was started in February 2009, is owned by russcastronovo, and has 232 members.

» Join This Project

Last updated January 11, 2010 18:56, by Tim Bray

Cloud API Specification - Requests to VDC Resources

The requests documented in this section are directed to VDC resources, which represent an entire Virtual Data Center. The VDC URI used to retrieve a given VDC representation will be defined by the service implementor, not by this API specification. From there on, the URIs for all resources related to this VDC can be discovered (directly or indirectly) from the VDC representation itself.

A VDC resource is read only from the perspective of this API, although its server side content is modified as a side effect of many other API requests. You should plan on performing the Get VDC request periodically to update your client's view of the VDC resource model.

Contents

1 Get VDC
2 Create Public Address
3 Create Volume

Get VDC

Retrieve information about a cloud service VDC.

Synopsis: GET {VDC URI}

Request Headers: Accept, Authorization, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: N/A.

Response Headers: Content-Length, Content-Type.

Response Message Body: VDC.

Response Status: 200, 400, 401, 403.

Example Request: Retrieve information about a VDC.

 GET /
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.VDC+json
 X-Cloud-Client-Specification-Version: 0.1

Example Response:

 HTTP/1.1 200 OK
 Content-Type: application/vnd.com.sun.cloud.VDC+json
 Content-Length: nnn
 
 {
   "name" : "Example VDC",
   "uri" : "http://example.com/vdc/123456", 
   "addresses" : [ ... ],
   "cluster" : { ... },
   "tags" : [ ... ],
   "volumes": [ ... ],
   "vm_templates" : "http://example.com/templates/catalog"
 }

Create Public Address

Request the Allocation of a new Public Address for use in this VDC. Most of the fields of a Public Address resource are automatically set in the course of its use; the only field specified at creation time is its logical name. The request is a POST to the URI of the VDC; the Content-Type MUST be "application/vnd.com.sun.cloud.PublicAddress+json"

Synopsis: POST { URI of VDC }

Request Headers: Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: Public Address.

Response Headers: Content-Length, Content-Type.

Response Message Body: Status for use in tracking Address allocaiton process.

Response Status: 202, 400, 401, 403, 404.

Status "op" Value: "new-Address".

Status "target_uri" identifies: The new Public Address once it is allocated.

Example 1 Request: Create a new Public Address named Load Balanced.

 POST /vdcs/vdc001
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.PublicAddress+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.PublicAddress+json
 X-Cloud-Specification-Version: 0.1
 
 {
  "name" : "Load Balanced"
 }

Example 1 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-Address",
   "progress": 100,
   "target_uri": "/addresses/107.236.66.83",
   "status_uri": "/statuses?op=na&r=0389.aa6",
   "status": 201
 }

Create Volume

Request the creation of a WebDAV volume on the storage service for the owner of this VDC. Most of the fields of a Volume resource are automatically set in the course of its use; the only field required at creation time is its logical name. The request is a POST to the URI of the VDC; the Content-Type MUST be "application/vnd.com.sun.cloud.Volume+json"

Synopsis: POST { URI of VDC }

Request Headers: Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: Volume.

Response Headers: Content-Length, Content-Type.

Response Message Body: Status for use in tracking volume-creation progress.

Response Status: 202, 400, 401, 403, 404.

Status "op" Value: "new-Volume".

Status "target_uri" identifies: The new Volume once it is created.

Example Request: Create a new Volume named backups.

 POST /vdcs/vdc001
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Volume+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.Volume+json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   "name" : "backups",
   "tags" : [ "default" ]
 }

Example Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-Volume",
   "progress": 0,
   "target_uri": "/volumes/1234567890",
   "status_uri": "/statuses?op=nv&name=backups"
 }