VMware VCLOUD API 1.0 - API - API Versioning; Link

VMware, Inc. 147
Chapter 8 XML Representations in the vCloud API
Link
ALinkelementdefinesahyperlinkwitharelationship,URI,andanoptionalnameandmediatype.Formore
informationabouthowLinkelementsareusedandalistofthevaluesallowedfortherelattribute,see“Links
andLinkRelations”onpage 15.
Thiselementisread‐only.
API Versioning
vCloud APIschemaversioninformationappearsinthevaluesofthexsi:schemaLocationandxmlns
attributesinaresponsedocument.Forexample,aresponsebodythatusedschemaversion1.0wouldinclude
thefollowingattributes:
xsi:schemaLocation="http://vcloud.example.com/api/v1.0/schema/master.xsd"
xmlns="http://www.vmware.com/vcloud/v1"
Todiscovertheschemaversionssupportedbyaserver,aclientcanmakeanunauthenticatedGETrequestto
awell‐knownURLontheserver,asshowninExample 8‐2.Theresponsetothiskindofrequestisa
SupportedVersionsdocument,fromwhichtheclientcanderiveinformationaboutthe
mediatypesand
schemalocationsusedbytheversionoftheAPIthattheserversupports.Theresponsecontainsa
MediaTypeMappingelementforeachmediatypedefinedbytheAPI.(Theexampleshowsonlyafewofthese
elements.)TheresponsealsoincludesaLoginUrlelement,whichcontainsaURLthat
aclientcanusetoobtain
anauthenticationtoken.FormoreinformationaboutusingtheLoginUrl,see“Authentication”onpage 18.
Example 8-2. API Version Request
Request:
GET http://vcloud.example.com/api/versions
Response:
200 OK
Content-Type: text/xml
...
<SupportedVersions ...>
<VersionInfo>
<Version>1</Version>
<LoginUrl>http://vcloud.example.com/api/v1/login</LoginUrl>
<MediaTypeMapping>
<MediaType>application/vnd.vmware.vcloud.org+xml</MediaType>
<ComplexTypeName>CatalogType</ComplexTypeName>
<SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation>
</MediaTypeMapping>
<MediaTypeMapping>
UNKNOWN TherequestraisedanexceptionthatdidnotmatchanyHTTPstatus
code.
UNSUPPORTED_MEDIA_TYPE Thewrongcontenttypewasspecified fortherequest.
Table 8-6. Minor Error Codes (Continued)
Error Code Description of Error
Schema
Name Min Max Type Description
rel 1 1 RelationType Relationofthelinktothereferencedobject
href 1 1 xs:anyURI Hyperlinktothereferencedobject
type 0 1 xs:string Mediatypeofthereferencedobject.Linkstoactionsdonot
haveamediatype.
name 01 xs:string Nameofthereferencedobject.LinkstoTasksandactions
donothavenames.