VMware VCLOUD API 1.0 - API

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
1MakeanAPIversionrequesttoavCloudservicetoobtaintheloginURLforthatservice.Formore
information,see“A P I Versioning”onpage 147.
2Make
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.