Responses - VMware VCLOUD API 1.0 - API Programming Manual

vCloud API Programming Guide

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

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:
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.
N Certain administrative operations have special authentication requirements. For more information, see
OTE
"Administrator Credentials and Privileges" on page 93.

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.
Table 1-2. HTTP Status Codes Returned by the vCloud API
Status Code
200 OK
201 Created
202 Accepted
204 No Content
303 See Other
400 Bad Request
18
token
Status Description
The request is valid and was completed. The response includes a document body.
The request is valid. The requested object was created and can be found at the URL specified in
the Location header.
The request is valid and a task was created to handle it. This response is usually accompanied
by a task URL.
The request is valid and was completed. The response does not include a body.
The response to the request can be found at the URL specified in the Location header.
The request body is malformed, incomplete, or otherwise invalid.
21.
VMware, Inc.