VMware VCLOUD API 1.0 - API

VMware, Inc. 19
Chapter 1 Introducing the VMware vCloud API
Configuring the vCloud API URL
ThebaseURLusedinhrefvaluesincludesthefully‐qualifieddomainnameoftheserverhost.Incaseswhere
thishostnamecannotberesolvedfromtheclient(forexample,iftheCloudDirectorinstallationincludes
multipleserverhoststhatyouaccessthroughaloadbalancer)youcanspecifyaURL
fortheservertousewhen
constructinghrefstrings.Formoreinformation,seeConfiguretheExternalRESTAPIBaseURIintheCloud
DirectorAdministratorʹsGuide.
Related Publications
TheVMwareCloudDirectorAdministratorʹsGuideandVMwareCloudDirectorUser’sGuidecontaindetailed
informationaboutmanyoftheobjectsandoperationsreferredtointhisguide.MostusersofthevCloudAPI
willfindtheinformationinthosedocumentsvaluablewhendevelopingclientapplications.Toaccessthe
currentversions
oftheseandotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
About the Examples
ThisguideincludesmanyexamplesofHTTPrequestsandresponses.Theseexamplesareintendedtoshow
theworkflowandcontentassociatedwithspecifictypesofoperationssuchasbrowsing,managinginventory,
andoperatingvirtualsystems.Examplerequestsgenerallyconformtotheruleslistedin“RequestBodies”on
page 17.Mostexampleresponses
showonlythoseelementsandattributesthatarerelevanttotheoperation
beingdiscussed.Ellipses(…)indicateomittedcontentwithinresponsebodies.
HTTPContent‐Typeheadersareshownwhereneededforallexamplesthatarenotfragmentsofsomelarger
examplethatincludesthisheader.Althoughtheexamplesshowthesestrings
usingthecharactercaseinwhich
theyaredefinedbytheimplementation,thesestringsarecase‐insensitiveinrequests,andcanbereturnedin
eithermixedcaseorlowercasecharactersinresponses.OtherHTTPheaders,suchasDate,Content‐Length,
andServer,areomittedbecausetheyarenotrelevantto
thespecificsofanyexample.TheXMLversionand
encodingheader(<?xml version="1.0" encoding="UTF-8"?>)isnotincludedinmostexamples,although
itisarequiredpartofallrequestsandresponsesthatcontainanXMLbody.
Inaddition:
 UnsecuredURLs(http://)areusedintheexamples.Inpractice,mostsiteswillrequiretheuseofSSL
(https://).
 ObjectIDsshowninhrefattributevaluesappearassmallintegers(forexamplevapp-7ororg/3).Inthe
vCloudAPIsupportedbyCloudDirector,objectIDsare10‐digitdecimalintegers(forexample
vapp-124237959ororg/5738592905).
401Unauthorized Anauthorizationheaderwasexpectedbutnotfound.
403Forbidden Therequestinguserdoesnothaveadequateprivilegestoaccessoneormoreobjectsspecified
intherequest.
404NotFound Oneormoreobjectsspecifiedintherequestcouldnotbefoundinthespecifiedcontainer.
405MethodNot
Allowed
TheHTTP
methodspecifiedintherequestisnotsupportedforthisobject.
500InternalServer
Error
Therequestwasreceivedbutcouldnotbecompletedduetoaninternalerrorattheserver.
501NotImplemented Therequestisnotimplementedbytheserver.
503Service
Unavailable
Oneormoreservicesneededto
completetherequestarenotavailableontheserver.
Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)
Status Code Status Description