VMware VCLOUD API 1.0 - TECHNICAL NOTE Operating instructions

vCloud API Programming Guide
vCloud API 1.0
This document supports the version of each product listed and
supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.
EN-000180-00

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, Inc.
vCloud API Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
[e-mail]
Copyright © 2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3
Contents
AboutThisBook 11
1IntroducingtheVMwarevCloudAPI 13
vCloudObjectTaxonomy 13
vCloudOrganizations 13
Objects,References,andRepresentations 15
LinksandLinkRelations 15
vCloudClientWorkflowOverview 17
Requests 17
Responses 18
ConfiguringthevCloudAPIURL 19
RelatedPublications 19
AbouttheExamples 19
2HellovCloud:AStructuredRESTWorkflowExample 21
LoggingInandGettinganOrganizationList 21
BrowsinganOrganization 22
FindingavAppTemplate 23
GettingInformationAboutavDC 24
InstantiatingtheTemplateinthevDC 24
DeployingandPoweringOnthevApp 26
GettingInformationAboutthevApp 27
DisplayingtheConsole 29
RetrieveaScreenTicket 29
UsetheTicketwithvmware‐vmrc 30
DeletingthevApp 30
LoggingOut 30
MovingontoAdditionalUseCases 31
3Browsing 33
SummaryofBrowsingRequests 33
DiscoveringtheContentsofanOrganization,Catalog,orvDC 34
ListtheOrganizationsinavCloud 34
ListtheContentsofanOrganization 34
ListtheContentsofaCatalog 35
GetInformationAboutaCatalogItem 36
ListtheContentsofavDC 37
GettingMoreInformationAboutanObject 38
GetInformationAboutaMediaImage 38
GetInformationAboutavAppTemplate 39
GetInformationAboutavApporVirtualMachine 40
GetInformationAboutaNetwork 40

vCloud API Programming Guide
4VMware, Inc.
4Provisioning 41
SummaryofProvisioningRequests 41
UploadOVFtoCreateavAppTemplate 42
RestrictionsonUploadedContent 43
InitiatetheUpload 43
IncludingaManifest 45
UploadingtheFiles 45
ViewtheOVFDescriptorofavAppTemplate 47
DownloadavAppTemplateasOVF 47
EnableavAppTemplateforDownload 48
DisableavAppTemplateforDownload 49
UploadaMediaImage 50
CopyingandMoving 50
CopyorMoveaMediaImage 51
CopyorMoveavAppTemplate 51
CopyorMoveavApp 52
ChangingaNameorDescription 53
ChangetheNameorDescriptionofavAppTemplate 53
ChangetheNameorDescriptionofavApp 53
ChangetheNameorDescriptionofaMediaImage 54
DeleteavAppTemplate,vApp,orMediaImage 54
CatalogingvAppTemplatesandMediaImages 54
AddanItemtoaCatalog 54
RemoveanItemfromaCatalog 56
CatalogLinksinaVAppTemplateorMediaImage 56
ControllingAccess 56
ControlAccesstoCatalogs 56
5DatacenterOperations 59
SummaryofDatacenterOperationsRequests 59
vAppLifecycle 60
InstantiateavAppTemplate 61
AboutInstantiationParameters 62
AboutvAppNetworks 62
InstantiatingavAppTemplateUsingDefaultParameters 62
InstantiatingavAppTemplateUsingAdditionalParameters 62
RetrieveorModifytheCustomizationSectionofavAppTemplate 64
ComposeavApp 65
FindingVirtualMachineURLstoUseinaCompositionItem 66
RecomposeavApptoAddorRemoveVirtualMachines 67
CaptureavApptoCreateavAppTemplate 68
ReconfiguringvAppsandVirtualMachines 69
ReconfigureavApp 69
ReconfigureaVirtualMachine 73
DeployingandControllingvAppsandVirtualMachines 80
DeployavApporVirtualMachine 80
UndeployavApporVirtualMachine 81
PowerOnavApporVirtualMachine 81
PowerOffavApporVirtualMachine 82
ResetavApporVirtualMachine 82
SuspendavApporVirtualMachine 83
DiscardtheSuspendedStateofavApporVirtualMachine 83
ShutDownavApporVirtualMachine 84
RebootavApporVirtualMachine 84
ListMediaDevicesofaVirtualMachine 85

VMware, Inc. 5
Contents
InsertMediaIntoaVirtualMachine 85
EjectMediafromaVirtualMachine 86
GetaScreenThumbnailforaVirtualMachine 86
GetaScreenTicketforaVirtualMachine 87
ProvideUserInputRequestedbyaVirtualMachine 87
ControlAccesstovApps 89
RetrieveaTask 89
6AdministrativeOperations 91
SummaryofAdministrativeRequests 91
AdministratorCredentialsandPrivileges 93
AdministrativeObjectsandURLs 93
GetanAdministrativeViewofaCloud 93
OrganizationAdministration 94
CreateanOrganization 95
GetanAdministrativeViewofanOrganization 96
ListAllTasksOwnedbyanOrganization 97
ModifyanOrganization 97
EnableorDisableanOrganization 98
RemoveanOrganization 99
NetworkAdministration 99
ViewthePropertiesofanExternalNetwork 99
AddaNetworktoanOrganization 100
GetanAdministrativeViewofanOrganizationNetwork 101
ModifyanOrganizationNetwork 101
RemoveanOrganizationNetwork 102
vDCAdministration 102
ExaminetheContentsofaProvidervDC 103
ListtheOrganizationvDCsSupportedbyaProvidervDC 104
AllocateavDCtoanOrganization 104
GetanAdministrativeViewofavDC 106
ModifyavDC 106
EnableorDisableavDC 107
RemoveavDC 107
CatalogAdministration 107
CreateaCatalog 107
GetanAdministrativeViewofaCatalog 108
PublishaCatalog 109
ModifyCatalogMetadata 109
RemoveaCatalog 110
UserAdministration 110
CreateorImportaUser 110
GetanAdministrativeViewofaUser 112
ModifyUserMetadata 112
RemoveaUser 113
GroupAdministration 113
ImportaGroup 113
ViewGroupMetadata 114
ModifyGroupMetadata 114
RemoveaGroup 114

vCloud API Programming Guide
6VMware, Inc.
RoleAdministration 114
CreateaRole 114
ViewRoleMetadata 115
ModifyaRole 116
RemoveaRole 116
ViewaRight 116
7VMwarevSpherePlatformOperations 117
SummaryofvSpherePlatformOperationsRequests 117
ListvSpherePlatformOperationsandObjectsforavCloud 119
ListProvidervDCsinavCloud 120
ListExternalNetworksinavCloud 120
ListNetworkPoolsinavCloud 120
ListvCenterServersRegisteredtoavCloud 120
GetInformationAboutavCenterServer 120
ListAvailableResourcePoolsonavCenterServer 121
ModifyvCenterServerSettings 122
RegisteravCenterServerandvShieldManager 122
UnregisteravCenterServerandvShieldManager 123
ForceReconnectiontoavCenterServer 124
ListESX/ESXiHostsinavCloud 124
GetInformationAboutaHost 124
PrepareaHost 125
UnprepareaHost 126
EnableorDisableaHost 126
RepairaHost 126
UpgradeaHostAgent 127
CreateaProvidervDC 127
ExaminethevSphereObjectsinaProvidervDC 131
ModifyaProvidervDC 131
EnableorDisableaProvidervDC 132
RemoveaProvidervDC 132
CreateanExternalNetwork 133
GetInformationAboutanExternalNetwork 134
ModifyanExternalNetwork 135
RemoveanExternalNetwork 135
CreateaNetworkPool 136
GetInformationAboutaNetworkPool 137
ModifyaNetworkPool 137
RemoveaNetworkPool 138
ImportaVirtualMachinefromvCenter 138
DiscovertheVirtualMachinesinavCenter 138
ImportaVirtualMachineasavApp 139
ImportaVirtualMachineasavAppTemplate 140
8XMLRepresentationsinthevCloud API 141
AboutObjectRepresentations 141
Schema 141
ContentType 142
ObjectReferencePrototype 142
CommonDatatypes 142
PrimitiveXMLDatatypes 142
ComplexTypes 143

VMware, Inc. 7
Contents
CommonAttributes 143
name 144
href 144
type 144
status 144
XMLNamespaceIdentifiers 145
CommonElements 146
Description 146
Error 146
Link 147
APIVersioning 147
SupportedVersions 148
VersionInfo 148
Extensibility 148
VCloudExtension 149
9UserAPIReference 151
OrgList 151
Org 151
Vdc 152
StorageCapacity 153
ComputeCapacity 153
AvailableNetworks 153
ResourceEntities 154
ResourceEntity 154
OrgNetwork 154
Configuration 155
Catalog 160
CatalogItems 160
CatalogItem 160
Media 161
VAppTemplate 161
Children 162
VApp 162
Vm 163
Section 163
LeaseSettingsSection 164
StartupSection 164
CustomizationSection 164
NetworkConfigSection 165
NetworkConnectionSection 165
VirtualHardwareSection 167
OperatingSystemSection 167
GuestCustomizationSection 167
RasdItemsList 168
ScreenTicket 168
TasksList 168
Tasks 168
Task 168
10 RequestParametersReference 171
UploadVAppTemplateParams 171
InstantiateVAppTemplateParams 172
InstantiationParams 172

vCloud API Programming Guide
8VMware, Inc.
ComposeVAppParams 173
Item 173
NetworkAssignment 174
RecomposeVAppParams 174
DeployVAppParams 175
UndeployVAppParams 175
CaptureVAppParams 175
CloneMediaParams 176
CloneVAppTemplateParams 176
CloneVAppParams 176
MediaInsertOrEjectParams 177
VmPendingQuestion 177
VmQuestionAnswer 177
ControlAccessParams 177
AccessSettings 178
11 AdministrativeAPIReference 179
VCloud 179
OrganizationReferences 180
ProviderVdcReferences 180
RightReferences 180
RoleReferences 180
Networks 180
ExternalNetwork 180
AdminOrg 180
Settings 181
Users 185
Groups 185
Catalogs 185
Catalog 186
Vdcs 186
ProviderVdc 186
ComputeCapacity 187
StorageCapacity 188
NetworkPoolReferences 188
NetworkPoolReference 188
VdcReferences 188
AdminVdc 188
AllocationModel 190
User 190
Group 191
Role 191
RightReferences 191
RightReference 191
Right 192
12 vSpherePlatformExtensionsReference 193
VMWExtension 193
VMWProviderVdcReferences 194
VMWExternalNetworkReferences 194
VMWNetworkPoolReferences 194
VMWVimServerReferences 194
VMWHostReferences 194
VimServer 194

VMware, Inc. 9
Contents
VmObjectRefsList 195
VimObjectRef 195
ResourcePoolList 196
ResourcePool 196
ShieldManager 196
VMWProviderVdc 197
VMWNetworkPool 198
FencePoolType 198
PortGroupPoolType 198
VlanPoolType 198
VMWExternalNetwork 199
VlanRange 199
VMWHostReferences 199
Host 199
RequestParameters 200
PrepareHostParams 200
RegisterVimServerParams 200
ImportVmAsVAppParams 201
ImportVmAsVAppTemplateParams 201
AOVFandthevCloudAPI 203
AboutOVF 203
AboutOVFPackages 204
AboutOVAFiles 204
HowthevCloudAPIUsesOVF 204
VirtualMachines 204
VirtualDiskFiles 205
Networks 205
BAnIntroductiontoRESTforvCloudAPIUsers 207
HowRESTWorks 207
UsingthevCloudRESTAPI 207
RESTfulWorkflowPatterns 208
ForMoreInformationAboutREST 208
Index 209

vCloud API Programming Guide
10 VMware, Inc.

VMware, Inc. 11
ThevCloudAPIProgrammingGuideprovidesinformationaboutversion1.0ofthevCloudAPI.
VMwareprovidesmanydifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides
informationaboutthevCloudAPIfordevelopersthatareinterestedincreatingRESTfulclientsofVMware
CloudDirector.
ToviewthecurrentversionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto
http://www.vmware.com/support/pubs/sdk_pubs.html.
Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor
ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook.
Intended Audience
ThisguideisintendedforsoftwaredeveloperswhoarebuildingVMwareReadyCloudServices,including
interactiveclientsofVMwareCloudDirector.ThisguideassumesyouarefamiliarwithRepresentationalState
Transfer(REST)andRESTfulprogrammingconventions,theOpenVirtualizationFormatSpecification,and
VMwareVirtualmachinetechnology.Familiaritywithotherwidely‐deployedtechnologiessuchasXML,
HTTP,andtheWindowsorLinuxoperatingsystemsisalsoassumed.
VMware Technical Publications Glossary
VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions
oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto
[email protected].
About This Book
Table 1. Revision History
Revision Date Description
30AUG10 Version1.0

vCloud API Programming Guide
12 VMware, Inc.
Technical Support and Education Resources
Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions
ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
Online and Telephone Support
Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and
registeryourproducts,gotohttp://www.vmware.com/support.
Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto
http://www.vmware.com/support/services.
VMware Professional Services
VMwareEducationServicescoursesofferextensivehands‐onlabs,casestudyexamples,andcoursematerials
designedtobeusedason‐the‐jobreferencetools.Coursesareavailableonsite,intheclassroom,andlive
online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides
offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout
educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

VMware, Inc. 13
1
TheVMwarevCloudAPIprovidessupportfordeveloperswhoarebuildinginteractiveclientsofVMware
CloudDirectorusingaRESTfulapplicationdevelopmentstyle.vCloudAPIclientsandserverscommunicate
overHTTP,exchangingrepresentationsofvCloudobjects.TheserepresentationstaketheformofXML
elements.HTTPGETrequestsareusedtoretrievethecurrentrepresentationofanobject,HTTPPOSTand
PUTrequestsareusedtocreateormodifyanobject,andHTTPDELETErequestsaretypicallyusedtodelete
anobject.
ThischapterintroducesthevCloudAPIandincludesthefollowingtopics:
“vCloudObjectTaxonomy”onpage 13
“Objects,References,andRepresentations”onpage 15
“LinksandLinkRelations”onpage 15
“vCloudClientWorkflowOverview”onpage 17
“A b o u t theExamples”onpage 19
vCloud Object Taxonomy
ThevCloudAPIdefinesasetofobjectscommontocloudcomputingenvironments.Figure 1‐1illustratesthe
principalobjecttypes.
vCloud Organizations
AvCloudcontainsoneormoreorganizations.AvCloudorganizationisaunitofadministrationfora
collectionofusers,groups,andcomputingresources.Usersauthenticateattheorganizationlevel,supplying
credentialsestablishedbyanorganizationadministratorwhentheuserwascreatedorimported.
vCloud Users and Groups
Anorganizationcancontainanarbitrarynumberofusersandgroups.Userscanbecreatedbythe
organizationadministratororimportedfromadirectoryservicesuchasLDAP.Groupsmustbeimported
fromthedirectoryservice.Permissionswithinanorganizationarecontrolledthroughtheassignmentofrights
androlestousersandgroups.
vCloud Networks
Anorganizationcanbeprovisionedwithoneormorenetworks.Theseorganizationnetworkscanbe
configuredtoprovideservicessuchasDHCP,NAT,andfirewalls.
Introducing the VMware vCloud API 1

vCloud API Programming Guide
14 VMware, Inc.
Figure 1-1. vCloud Object Taxonomy
vCloud Virtual Datacenters
AvCloudvirtualdatacenter(vDC)isanallocationmechanismforresourcessuchasnetworks,storage,CPU,
andmemory.InavDC,computingresourcesarefullyvirtualized,andcanbeallocatedbasedondemand,
servicelevelrequirements,oracombinationofthetwo.
TherearetwokindsofvDCs:
ProvidervDCs.ThesevDCscontainalltheresourcesavailablefromthevCloudserviceprovider.
ProvidervDCsarecreatedandmanagedbyvCloudsystemadministrators.
OrganizationvDCs.ThesevDCsprovideanenvironmentwherevirtualsystemscanbestored,deployed,
andoperated.Theyalsoprovidestorageforvirtualmedia,suchasfloppydisksandCDROMs.
AnorganizationadministratorspecifieshowresourcesfromaprovidervDCaredistributedtothevDCsinan
organization.
vCloud Catalogs
Catalogscontainreferencestovirtualsystemsandmediaimages.Acatalogcanbesharedtomakeitvisibleto
othermembersofanorganization,andcanbepublishedtomakeitvisibletootherorganizations.AvCloud
systemadministratorspecifieswhichorganizationscanpublishcatalogs,andanorganizationadministrator
controlsaccesstocatalogsbyorganizationmembers.
vCloud Tasks
Long‐runningoperationsinitiatedbymembersofanorganizationcreatetasks,whicharekeptonthe
organization’staskslist.
Catalog 2
Catalogitem
em
em
em
Catalog 1
Catalog 3
vDC2 Catalogitem
Catalogitem
Catalogitem
Catalogitem
users
Media
vApp
template
Media
vApp
TasksList
Organization
vDC1
Media
vApp
template
Media
vApp
Network
Network
Catalogitem
em
em
em
groups

VMware, Inc. 15
Chapter 1 Introducing the VMware vCloud API
Virtual Systems and Media Images in a vCloud
VirtualsystemsandmediaimagesarestoredinavDCandcanbeincludedinacatalog.Mediaimagesare
storedintheirnativerepresentation(ISOorfloppy).Virtualsystemsarestoredastemplates,usinganopen
standardformat(OVF1.0).Thesetemplatescanberetrievedfromcatalogsandtransformedintovirtual
systems,calledvApps,throughaprocesscalledinstantiation,whichbindsatemplate’sabstractresource
requirementstoresourcesavailableinavDC.AvAppcontainsoneormoreindividualvirtualmachines(Vm
elements),alongwithparametersthatdefineoperationaldetailssuchas:
Howthecontainedvirtualmachinesareconnectedtoeachotherandtoexternalnetworks.
Theorderinwhichindividualvirtualmachinesarepoweredonoroff.
End‐userlicenseagreementtermsforeachvirtualmachine.
Deploymentleaseterms(typicallyinheritedfromthecontainingorganization)thatconstrainthevApp’s
consumptionofvDCresources
Accesscontrolinformationspecifyingwhichusersandgroupscanperformoperationssuchasdeploy,
poweron,modify,andsuspendonthevAppandthevirtualmachinesitcontains.
Objects, References, and Representations
ThevCloudAPIrepresentsobjectsinthevCloudasXMLdocumentsinwhichobjectpropertiesareencoded
aselementsandattributeswithtypedvaluesandanexplicitobjecthierarchydefinedbyanXMLschema.
EveryobjectinavCloudisuniquelyidentifiedbyaURL.ThisURLisconstructedbytheserverandreturned
inthevalueofthehrefattributeoftheXMLelementthatrepresentstheobject.Italsoappearsinvarious
elementsofLinkTypeandReferenceType.ThisURLservesasauniqueidentifierthatpersistsforthelifeof
theobjectandisneverre‐used.AlthoughURLshaveawell‐knownsyntaxandawell‐understood
interpretation,aclientshouldtreateachhrefasanopaquestring.Therulesthatgovernconstructionofhref
stringsbytheservermightchangeinfuturereleases.
Objecttypes,specifiedasMIMEcontenttypes,areincludedintheXMLrepresentationsoffirst‐classobjects
suchastheonesshowninFigure 1‐1.Formoreinformation,see“ContentType”onpage 142.
Links and Link Relations
ThevCloudAPImakesextensiveuseoflinks(URLs)toprovidereferencestoobjectsandtheactionsthatthey
support.Theselinksaretheprimarymechanismbywhichaservertellsaclienthowtoaccessandoperateon
anobject.Linksarecreatedbytheserver,andareread‐onlyattheclient.(Ifaclientrequestbodyincludesa
link,theserverignoresit.)
IntheXMLrepresentationofavCloudobject,eachlinkisdefinedinaLinkelementthathasthefollowing
form:
<Link rel=" relationship " type="application/vnd.vmware.vcloud.type+xml" href=" URL " name=" string "/>
TherelattributevaluedefinestherelationshipoftheobjectwhoseXMLrepresentationcontainstheLink
toatargetobject.TherelationshipalsoindicatestheHTTPrequesttypetousewhenmakingarequest
withthehrefattributeofthelink,asshowninTable 1‐1:
Table 1-1. Link Relationships and HTTP Request Types
rel Attribute Value Relation Description HTTP Request
add addsanitemtothiscontainer POST
alternate alinktoanalternaterepresentationofthisobject GET
catalogItem alinktothecatalogItemthatcontainsareferencetothisobject. GET
controlAccess applyaccesscontrols POST
copy notsupportedinthisrelease N/A
deploy deploythisobject POST

vCloud API Programming Guide
16 VMware, Inc.
Thetypeattributevaluedefinesthemediatype(HTTPContent‐Type)oftherequestorresponse
document.Thisattributeispresentonlyforlinkstoobjects.Itisnotpresentforlinkstoactions.
ThehrefattributevalueisaURL,whichshouldbeconsideredanopaqueidentifier(onethattheclient
shouldnotattempttoparseorinterpret).Anhrefuniquelyidentifies,andpersistsforthelifeof,the
referencedobject.Theseidentifiersareneverre‐used.
ThenameattributevalueoftheLinkisthesameasthenameofthereferencedobject.Actionlinksdonot
includeanameattribute.
disable disablethisobject POST
discardState discardthesuspendedstateofthisvirtualmachine POST
down thereferencedobjectiscontainedbythisobject GET
download:alternate notsupportedinthisrelease N/A
download:default defaultdownloadlocationforthisfile GET
edit modifiesthisobject PUT
enable enablethisobject POST
extension notsupportedinthisrelease N/A
media:ejectMedia ejectvirtualmediafromavirtualdevice POST
media:insertMedia insertvirtualmediainavirtualdevice POST
move notsupportedinthisrelease N/A
ova notsupportedinthisrelease N/A
ovf theOVFrepresentationofthisvAppTemplate GET
power:powerOff poweroffthereferencedobject POST
power:powerOn poweronthisobject POST
power:reboot rebootthisobject POST
power:reset resetthisobject POST
power:shutdown shutdownthisobject POST
power:suspend suspendthisobject POST
publish publishthiscatalog POST
recompose recomposethisvApp POST
reconnect reconnectthisvCenterServer POST
register registerthisvCenterServer POST
remove removethisobject DELETE
repair repairthishost POST
screen:acquireTicket acquireascreenticketforthisvirtualmachine GET
screen:thumbnail thumbnailviewofavirtualmachinescreen,inpngformat GET
task:cancel notsupportedinthisrelease N/A
undeploy undeploythisobject POST
unregister unregisterthisvCenterServer POST
up thereferencedobjectcontainsthisobject GET
upgrade upgradethishost POST
upload:alternate notsupportedinthisrelease N/A
upload:default defaultuploadlocationforthisfile PUT
Table 1-1. Link Relationships and HTTP Request Types (Continued)
rel Attribute Value Relation Description HTTP Request

VMware, Inc. 17
Chapter 1 Introducing the VMware vCloud API
Linksprovideawayfortheservertoinformaclientaboutobjectrelationshipsandtheoperationsthatobjects
support.Forexample,acontainersuchasanorganizationorcatalogcanreturnlinkstotheobjectsitcontains,
andavirtualsystem(avApporVm)cancontainactionlinksthatenableoperationssuchaspowerstatechanges
orvirtualdevicereconfiguration.Linkstoactionsandcontainedobjectsareomittedfromresponsesifthe
requestwasmadebyauserwhohasinsufficientprivilegestoaccesstheobjectorperformtheaction.Action
linksarealsoomittedwhentheactioncannotbeperformed(poweringonavirtualmachinethatisalready
poweredon,forexample).
vCloud Client Workflow Overview
ClientsofthevCloudAPIimplementaRESTfulworkflow,makingHTTPrequeststotheserverandretrieving
theinformationtheyneedfromtheserver’sresponses.
Requests
ClientsmakeHTTPrequeststovCloudURLs,hrefattributevalueswhicharetypicallyprovidedbytheserver
inresponsetoGETrequestsbytheclient.EveryvCloudhasawell‐knownURLfromwhichaclientcangetthe
server’sloginURLandthelistofvCloudAPIversionsthattheserversupports,alongwithadditional
information(see“A P I Versioning”onpage 147).Afteraclienthasloggedin,allvCloudAPIURLscanbe
discoveredbymakingGETrequeststoURLslistedintheloginresponseandtheURLscontainedinresponses
tothoserequests.
Request Headers
Allrequestsfromauthenticatedclientsmustincludeanauthenticationheader.See“Authentication”on
page 18.
RequeststhatincludeadocumentbodymuststartwiththeappropriateHTTPContent‐Typeheader.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 entityis
application/vnd.vmware.vcloud.catalogItem+xml.
<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml"
href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with
vsftpd"/>
AnyrequestthatincludesaCatalogItem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vCloudAPI,
thisstringiscase‐insensitiveinrequests,andcanbereturnedineithermixedcaseorlowercasecharactersin
responses.
Formoreinformation,see“ContentType”onpage 142.
Request Bodies
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinarequestbodytoagree
inbothorderandnumberwiththeschema.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”onpage 145.
Ifmultiplenamespacesarerepresentedintherequest,XMLnamespaceattributesmustincludean
identifyingprefix,andthatprefixmustbeusedwithelementsfromthatnamespace.See“XML
NamespacePrefixesinRequestandResponseBodies”onpage 146.
NOTEWhenaclientusesalinktoreferenceanobject,onlythehrefattributeisrequired.Thenameandtype
areignored.

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.
NOTE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.

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

vCloud API Programming Guide
20 VMware, Inc.