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 VMware Cloud Director installation has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the VMware Cloud Director 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 VMware Cloud Director 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 by the type of requested operation: create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD. Each type of request is characterized by the use of specific HTTP verb to access a URL found in a Link element that has an operation-specific value for its rel (relation) attribute.

Table 1. CRUD Operations Summary
Operation Type HTTP Verb Link Relation Operation Summary
Create POST add Creates an object.
Retrieve GET down Retrieves the representation of an existing object in its current state.
Update PUT edit Modifies an existing object.
Delete DELETE remove Deletes an existing object. If the object is a container, you must remove all of its contents before you can delete it.
For example, this Link element indicates that you can use the URL https://vcloud.example.com/api/admin/org/26 to update the Org object that contains it. 
<Link
   rel="edit"
   type="application/vnd.vmware.admin.organization+xml"
   href="https://vcloud.example.com/api/admin/org/26" />
The implied HTTP verb is PUT.
Important:

Request bodies must contain all required elements and attributes, even if you are not changing their values. Because optional elements and attributes typically revert to default values if they are omitted or empty, it is a best practice to include optional elements in request bodies that modify existing objects. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes are read-only and cannot be modified. See the schema reference for details.

Security

HTTP communications between a VMware Cloud Director API client and server are secured with SSL. API clients must also complete a login request to receive an authorization token that must be included in all subsequent requests.

Request Headers

The following HTTP headers are typically included in VMware Cloud Director API requests:

Accept
All requests must include an HTTP Accept header that specifies the type of response that is expected. Two forms of this header are supported: 
Accept: application/*
Accept: application/vnd.vmware.vcloud.type+xml
The second form constrains acceptable responses to a type defined the VMware Cloud Director API schema. Accept headers of the following form are also allowed in VMware Cloud Director API requests, but they are not compliant with RFC 2616 and might not be accepted by future versions of the VMware Cloud Director API. 
Accept: application/*+xml
In addition, two key-value pairs are supported in the Accept header:
Table 2. Accept Header Key-Value Pairs
Key Value Requirement Description
version Any supported VMware Cloud Director API version number Required Specifies the VMware Cloud Director API version that the client is using.
multisite global Optional Specifies that the request fans out to all member organizations. See Configuring and Managing Multisite Deployments.
local Optional Specifies that the request does not fan out but includes multisite metadata included on fan-out. See Configuring and Managing Multisite Deployments.
One or more location IDs Optional Multiple location IDs must be colon separated. Specifies that the request fans out only to the specified locations. See Configuring and Managing Multisite Deployments.
For example, the following header indicates that the request is from a VMware Cloud Director API version 30.0 client, and accepts any type defined in that API version: 
Accept: application/*;version=30.0
In general, client requests can access objects defined by any version of the VMware Cloud Director API that is less than or equal to the version specified in the Accept header. See API Versions.
Accept-Encoding
By default, the system 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 64 KB are never compressed.
Accept-Language
Message strings in ErrorType responses are localized. To specify the language desired in responses, use the Accept-Language request header. To request a response with message strings localized to French, use the following header: 
Accept-Language: fr
Authorization
All requests to create a VMware Cloud Director API session must include an Authorization header of the form prescribed by the identity provider that your organization uses. See Create a VMware Cloud Director API Session. After you have established a session, you can use the value of the X-VMWARE-VCLOUD-TOKEN-TYPE and X-VMWARE-VCLOUD-ACCESS-TOKEN headers in the Session response to construct an Authorization header for use with subsequent requests.
Content-Type
Requests that include a body must include an appropriate HTTP Content-Type header. Content types for all elements are listed 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"  
   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 VMware Cloud Director API, this string is case-insensitive in requests. The string can be returned in either mixed case or lowercase characters in responses.
x-vcloud-authorization
This header is returned with the Session response after a successful log-in to the integrated identity provider. As of API version 30, it is deprecated in favor of the X-VMWARE-VCLOUD-ACCESS-TOKEN value returned when you create a Session. If backward compatibility is a concern, you can supply x-vcloud-authorization instead of an Authorization header in most requests that do not fan out to members of an organization or site association. See Configuring and Managing Multisite Deployments.
X-VMWARE-VCLOUD-AUTH-CONTEXT
Unless you are making a request to the same organization that authenticated you, you must include this header in the request. You must specify a value that is the name of the organization to which you are making the request and that organization must be associated with the organization that authenticated you. See Configuring and Managing Multisite Deployments.
X-VMWARE-VCLOUD-CLIENT-REQUEST-ID
The value of this header is used to build a request ID returned in the value of the X-VMWARE-VCLOUD-REQUEST-ID header (see Response Headers). The value of this header cannot contain more than 128 characters drawn from the set of letters, numbers, and the hyphen (-). Values with invalid characters are ignored. Values with more than 128 characters are truncated.

Request Bodies

VMware Cloud 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.

Request Limits

To guard against denial-of-service attacks, VMware Cloud Director imposes the following limits on VMware Cloud Director API requests:
  • Requests cannot exceed 512 KB.
  • Requests cannot contain more than 4096 XML elements.
  • Requests cannot have a depth greater than 100.