VMware vCloud vCloud Director 1.0 User guide

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-01

VMware, Inc.

3401 Hillview Ave.

Palo Alto, CA 94304

www.vmware.com

2 VMware, 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:

docfeedback@vmware.com

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

1 Introducing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

2 Hello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

3 Browsing 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

4 Provisioning 41

SummaryofProvisioningRequests 41

UploadOVFtoCreateavAppTemplate 42

vCloud API Programming Guide

4 VMware, Inc.

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

5 Datacenter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 8 4

RebootavApporVirtualMachine 84

ListMediaDevicesofaVirtualMachine 85

InsertMediaIntoaVirtualMachine 85

EjectMediafrom

aVirtualMachine 86

GetaScreenThumbnailforaVirtualMachine 86

VMware, Inc. 5

Contents

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

6 Administrative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 9 9

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

RoleAdministration 114

CreateaRole 114

ViewRoleMetadata 115

ModifyaRole 116

RemoveaRole 116

ViewaRight 116

vCloud API Programming Guide

6 VMware, Inc.

7 VMware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

8 XML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

CommonAttributes 143

name 144

href 144

type 144

status 144

XMLNamespaceIdentifiers 145

CommonElements 146

Description 146

Error 146

VMware, Inc. 7

Contents

Link 147

APIVersioning 147

SupportedVersions 148

VersionInfo 148

Extensibility 148

VCloudExtension 149

9 User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

ComposeVAppParams 173

Item 173

NetworkAssignment 174

RecomposeVAppParams 174

DeployVAppParams 175

UndeployVAppParams 175

CaptureVAppParams 175

CloneMediaParams 176

CloneVAppTemplateParams 176

vCloud API Programming Guide

8 VMware, Inc.

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

VmObjectRefsList 195

VimObjectRef 195

ResourcePoolList 196

ResourcePool 196

ShieldManager 196

VMWProviderVdc 197

VMWNetworkPool 198

FencePoolType 198

PortGroupPoolType 198

VlanPoolType 198

VMware, Inc. 9

Contents

VMWExternalNetwork 199

VlanRange 199

VMWHostReferences 199

Host 199

RequestParameters 200

PrepareHostParams 200

RegisterVimServerParams 200

ImportVmAsVAppParams 201

ImportVmAsVAppTemplateParams 201

A OVF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

B An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

08MAR11 GuestCustomizationSectionnotallowedinInstantiationParams

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

Catalog 1

Catalog 3

vDC2

Catalogitem

users

Media

vApp

template

Media

vApp

TasksList

Organization

vDC1

Media

vApp

template

Media

vApp

Network

Catalogitem

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“AP 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.

N

OTE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.

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.

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.

Page is loading ...

VMware vCloud vCloud Director 1.0 User guide

VMware vCloud vCloud Director 1.0 User guide

Related papers

Other documents