VMware VCLOUD API 1.0 - API - vCloud Client Workflow Overview

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.