5.5
Table Of Contents
- vCloud API Programming Guide
- Contents
- vCloud API Programming Guide
- About the VMware vCloud API
- Hello vCloud: A Simplified RESTful Workflow
- Exploring a Cloud
- Summary of vCloud API Browsing Requests
- Retrieve the Login URL and List of Supported API Versions
- Create a Login Session Using the Integrated Identity Provider
- Retrieve a List of Organizations Accessible to You
- Retrieve an Administrative View of a Cloud
- Retrieve a List of vSphere Platform Operations and Objects for a Cloud
- Provisioning an Organization
- Summary of vCloud API Provisioning Requests
- Upload an OVF Package to Create a vApp Template
- Download a vApp or vApp Template as OVF
- Upload a Media Image
- Download a Media Image
- Capturing and Importing vApps
- Managing Catalog Items
- Creating and Using Independent Disks
- View or Change the Owner of an Object
- Controlling Access to vApps and Catalogs
- Deploying and Operating vApps
- Summary of vCloud API vApp and Virtual Machine Operations Requests
- Create a vApp From a Template
- Create a vApp From an OVF Package
- Compose a vApp From Existing Virtual Machines
- Recompose a vApp to Add or Remove Virtual Machines
- Clone a vApp
- Capture a vApp as a Template
- Update vApp Access Controls
- Provide User Input Requested by a Virtual Machine
- Attach or Detach an Independent Disk
- Creating and Using vApp Snapshots
- Operate a vApp
- Configuring vApps and Virtual Machines
- Retrieve the Configuration Links for a vApp
- Retrieve the Configuration Links for a Virtual Machine
- Update Multiple Sections of a Virtual Machine
- Retrieve or Update a Modifiable Section
- Update a vApp Network Configuration
- Update the NetworkConnectionSection of a Virtual Machine
- Retrieve or Modify the CPU Configuration of a Virtual Machine
- Retrieve or Modify the GuestCustomizationSection of a Virtual Machine
- Retrieve or Modify ProductSection Elements
- Retrieve or Modify Groups of Related Sections in a Virtual Machine
- Retrieve or Modify the Hard Disk Configuration of a Virtual Machine
- Update the Storage Profile for a Virtual Machine
- Creating and Managing Organizations
- Summary of Administrative Requests
- Administrator Credentials and Privileges
- Organization Administration
- VDC Administration
- Network Administration
- Catalog Administration
- User and Group Administration
- Working With Roles and Rights
- Managing and Monitoring a Cloud
- Summary of System Administration Requests
- Retrieve or Update System Settings
- Attach a vCenter Server
- Finding Available vCenter Resources
- Create a Provider VDC
- Create an External Network
- Create a Network Pool
- Import a Virtual Machine from vCenter
- Relocate a Virtual Machine to a Different Datastore
- Truststore and Keytab Maintenance
- Retrieve the vSphere URL of an Object
- Working With Object Metadata
- Using the Query Service
- Configuring and Using Blocking Tasks and Notifications
- vCloud Director Extension Services
- XML Representations in the vCloud API
- Index
n
If multiple namespaces are represented in the request, XML namespace attributes must include an
identifying prefix, and that prefix must be used with all elements from that namespace.
n
All required elements must appear in request bodies. All elements that appear in request bodies must
appear in the order that the schema establishes, and with content that conforms to the type constraint
that the schema specifies.
Request Limits
To guard against denial-of-service attacks, vCloud Director imposes the following limits on vCloud API
requests:
n
Requests cannot exceed 512 KB.
n
Requests cannot contain more than 4096 XML elements.
n
Requests cannot have a depth greater than 100.
vCloud API REST Responses
All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type
header. Response content depends on the request. Some responses include a document body, some include
only a URL, and some are empty.
Response Content
Response content depends on the requested operation. The response to a GET request is typically the
complete representation of an existing object. The response to a PUT or POST request always contains
values for the href, name, and id attributes of the object being created or updated. It also contains at most
one Task element that you can retrieve to track the progress of the operation. When the Task completes with
a status of success, a GET request to the object's href returns all properties of the object. If the Task
completion status is not success, the object is in an indeterminate state, and should be deleted.
HTTP Response Codes
A vCloud API client can expect a subset of HTTP status codes in a response.
Table 1‑3. HTTP Status Codes that the vCloud API Returns
Status Code Status Description
200 OK The request is valid and was completed. The response
includes a document body.
201 Created The request is valid. The requested object was created and
can be found at the URL specified in the Location header.
202 Accepted The request is valid and a task was created to handle it.
This response is usually accompanied by a Task element.
204 No Content The request is valid and was completed. The response does
not include a body.
400 Bad Request The request body is malformed, incomplete, or otherwise
invalid.
401 Unauthorized An authorization header was expected but not found.
403 Forbidden The requesting user is not authenticated or does not have
adequate privileges to access one or more objects specified
in the request.
404 Not Found One or more objects specified in the request could not be
found in the specified container.
405 Method Not Allowed The HTTP method specified in the request is not supported
for this object.
vCloud API Programming Guide
20 VMware, Inc.