VMware VCLOUD API 1.0 - TECHNICAL NOTE, Programming Manual

Page: 18 / 212

vCloud API Programming Guide
18 VMware, Inc.

All required elements must appear in request bodies. All elements that appear in request bodies must
appear in the order established by the schema, and with content that conforms to the type constraint
specified in the schema. See “Schema Validation” on page 142.
Authentication
HTTP communications between a vCloud client and server are typically secured with SSL. In addition, the
vCloud API implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to obtain
a token that it can use to authenticate individual HTTP requests.
To obtain and use an authentication token, a client must first discover the server’s login URL, and then POST
a login request to that URL, supplying the credentials of an authorized user.
To obtain and use an authentication token
1 Make an API version request to a vCloud service to obtain the login URL for that service. For more
information, see “API Versioning” on page 147.
2 Make an HTTP POST request to the login URL, as shown in Example 2 ‐ 1 on page 21 .

If the authentication header is missing, the server returns HTTP response code 401.

If the credentials supplied in the authentication header are invalid, the server returns HTTP response
code 401.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include
an authorization header of the form:
x-vcloud-authorization:
token
This header must be included in each subsequent vCloud API request.
The response body is an OrgList element, which is a list of all organizations that the user can access.
The authentication token expires after a configurable interval of client inactivity. The default is 30 minutes after
the token is created. After the token expires, all requests fail with HTTP response code 401 until the client logs
in again to obtain a new token.
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.
Status Codes
Table 1 ‐ 2 lists the subset of HTTP status codes that a vCloud API client can expect in a response.
N
OTE
Certain administrative operations have special authentication requirements. For more information, see
“Administrator Credentials and Privileges” on page 93.
Table 1-2. HTTP Status Codes Returned by the vCloud API
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 URL.
204 No Content The request is valid and was completed. The response does not include a body.
303 See Other The response to the request can be found at the URL specified in the Location header.
400 Bad Request The request body is malformed, incomplete, or otherwise invalid.