To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests.

Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the of vCloud API that the server supports. For each version, the response lists the names and MIME types of the complex types defined in the version's XML namespace, and the version login URL. A system administrator can use that URL to authenticate to the cloud by logging in to the System organization. An authenticated user can discover other vCloud API URLs by making GET requests to URLs retrieved from the login response, and the URLs contained in responses to those requests. See Exploring a Cloud.

Requests are typically categorized in terms of the type of requested operation: create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

CRUD Operations Summary

Operation Type

HTTP Verb

Operation Summary

Create

POST

Creates a new object.

Retrieve

GET

Retrieves the representation of an existing object.

Update

PUT

Modifies an existing object.

Delete

DELETE

Deletes an existing object.

HTTP communications between a vCloud API client and server are secured with SSL. The vCloud API also implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to authenticate individual HTTP requests by including an authentication header in the request. See Logging In.

The following HTTP headers are typically included in vCloud API requests:

Accept

All requests must include an HTTP Accept header that designates the API version that the client supports. The following header indicates that the request is for vCloud API version 5.1:

Accept: application/*+xml;version=5.1

Valid values for the HTTP Accept header in this release are:

version=5.1

The request is from a vCloud API version 5.1 client.

version=1.5

The request is from a vCloud API version 1.5 client.

Requests that specify API version 5.1 cannot access objects that do not exist in the vCloud API version 5.1 namespace.

Accept-Encoding

By default, vCloud Director returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. (Requests cannot be compressed.) To request a response to be returned as compressed XML, include the following header:

Accept-Encoding: gzip

The response is encoded using gzip encoding as described in RFC 1952, and includes the following header:

Content-Encoding: gzip

In the default configuration, responses smaller than 64KB are never compressed.

Authorization

All requests from authenticated clients must include an Authorization header. See Logging In for details about the value of this header.

Content-Type

Requests that include a body must start with the appropriate HTTP Content-Type header. Content types for all elements are included in the schema reference. In addition, the type attribute of a response body indicates the content type of the document. For example, this response fragment indicates that the content type associated with a CatalogItem object is application/vnd.vmware.vcloud.catalogItem+xml.

<CatalogItem 
   type="application/vnd.vmware.vcloud.catalogItem+xml" 
   href="https://vcloud.example.com/api/catalogItem/221" 
   name="Ubuntu Template with vsftpd"/>

A POST or PUT request that supplies a CatalogItem in the request body requires the following Content-Type header:

Content-Type: application/vnd.vmware.vcloud.catalogItem+xml

When it appears as the value of a Content-Type header or the type attribute of an element in the vCloud API, this string is case-insensitive in requests, and can be returned in either mixed case or lowercase characters in responses.

vCloud Director uses a validating XML parser that requires elements in a request body to agree with the schema in order and number. Request bodies are rejected as invalid unless they meet the following criteria:

XML namespace attributes must be supplied for all namespaces represented by elements in the request. See XML Namespace Identifiers.

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.

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.