VMware VCLOUD API 1.0 - API

VMware, Inc. 207
B
REST,anacronymforRepresentationalStateTransfer,isatermthathasbeenwidelyemployedtodescribean
architecturalstylecharacteristicofprogramsthatrelyontheinherentpropertiesofhypermediatocreateand
modifythestateofanobjectthatisaccessibleataURL.
Thisappendixincludesthefollowing
topics:
 “HowRESTWorks”onpage 207
 “UsingthevCloudRESTAPI”onpage 207
 “ForMoreInformationAboutREST”onpage 208
How REST Works
IfaURLofsuchanobjectisknowntoaclient,theclientcanuseanHTTPGETrequesttodiscoverthe
propertiesoftheobject.ThesepropertiesaretypicallycommunicatedinastructureddocumentwithanHTTP
Content‐TypeofXMLorJSON,thatprovidesarepresentationofthe
stateoftheobject.InaRESTfulworkflow,
documents(representationsofobjectstate)arepassedbackandforth(transferred)betweenaclientanda
servicewiththeexplicitassumptionthatneitherpartyneedknowanythingaboutanobjectotherthanwhatis
presentedinasinglerequestorresponse.The
URLsatwhichthesedocumentsareavailableareoften“sticky,”
inthattheypersistbeyondthelifetimeoftherequestorresponsethatincludesthem.Theothercontentofthe
documentsisnominallyvaliduntiltheexpirationdatenotedintheHTTPExpiresheader.
Using the vCloud REST API
A“RESTAPI”isinsomewaysanunfortunateterm,sincetheapplicationprogramswrittentoaRESTAPI
actuallyuseHTTPrequests(whichareoftenexecutedbyascriptorotherhigher‐levellanguage)asawayof
makingwhatareessentiallyremoteprocedurecallsthatcreate,modify,ordelete
theobjectsdefinedbythe
API.ThisRESTAPI(andothers)isdefinedbyacollectionofXMLdocumentsthatrepresenttheobjectson
whichtheAPIoperates.Theoperationsthemselves(HTTPrequests)aregenerictoallHTTPclients.
TowriteaRESTfulclient,youneedtounderstandonlytheHTTP
protocolandthesemanticsofstandard
HTMLmarkup.TousethevCloudAPIeffectivelyinsuchaclient,youneedtoknowthreethings
 thesetofobjectsthattheAPIsupports,andwhattheyrepresent(WhatisavDC?Howdoesitrelatetoan
organizationorcatalog?)
 howtheAPIrepresentstheseobjects(WhatdoestheXMLschemaforanOrglooklike?Whatdothe
individualelementsandattributesrepresent?)
 howtheclientreferstoanobjectonwhichitwantstooperate(WherearethelinkstoobjectsinavDC?
Howdoesaclientobtainandusethem?)
Toanswerthesequestions,youneedtounderstandthevCloudAPIXMLschemas.Theseschemasdefinea
numberofXMLtypes,
manyofwhichareextendedbyothertypes.ThevCloudAPIschemasalsouseand
extendtypesdefinedbytheOpenVirtualizationFormat.TheXMLelementsdefinedintheseschemas,along
withtheirattributesandcompositionrules(minimumandmaximumnumberofelementsorattributes,for
An Introduction to REST for vCloud
API Users
B