Links and Link Relations

The vCloud API makes extensive use of Link elements to provide references to objects and the actions that they support. These elements are the primary mechanism by which a server tells a client how to access and operate on an object.

The server creates Link elements in a response body. They are read-only at the client. If a request body includes a Link element, the server ignores it.

Attributes of a Link Element

In the XML representation of a vCloud object, each Link element has the following form:

<Link rel="relationship"
   type="application/vnd.vmware.vcloud.object_type+xml"
   href="URL" 
   name="string"/>

Attribute values in a Link element supply the following information:

rel	Defines the relationship of the link to the object that contains it. A relationship can be the name of an operation on the object, a reference to a contained or containing object, or a reference to an alternate representation of the object. The relationship value implies the HTTP verb to use when you use the link's href value as a request URL.
type	The object type, specified as a MIME content type, of the object that the link references. This attribute is present only for links to objects. It is not present for links to actions.
href	An object reference, expressed in URL format. This reference includes the object identifier portion of the id attribute value, and supplies additional information, including the current location of the object when accessed in a specific view. 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 how the server constructs href strings might change in future releases.
name	The name of the referenced object, taken from the value of that object's name attribute. Action links do not include a name attribute.

Link Relationships and HTTP Request Types
rel Attribute Value	Action or Relationship Description	Implied HTTP Verb
abort	Abort this blocking task.	POST
add	Add an item to this container.	POST
alternate	References an alternate representation of this object.	GET
answer	Provide user input requested by a virtual machine.	POST
authorization:check	Check whether an extension service operation is authorized for an entity.	POST
blockingTask	A list of pending blocking task requests in this cloud.	GET
bundle:upload	Upload an extension service localization bundle.	PUT
bundles:cleanup	Remove unused extension service localization bundles.	POST
catalogItem	References the CatalogItem object that refers to this object.	GET
certificate:reset	Removes the SSL certificate used by this service.	POST
certificate:update	Updates the SSL certificate used by this service.	POST
checkCompliance	Check that this virtual machine is using a storage profile of the intended type.	POST
consolidate	Consolidate this virtual machine.	POST
controlAccess	Apply access controls to this object.	POST
copy	Reserved	N/A
customizeAtNextPowerOn	Force guest customization to be applied the next time this virtual machine is powered on.	POST
deploy	Deploy this vApp.	POST
disable	Disable this object.	POST
discardState	Discard the suspended state of this virtual machine.	POST
disk:attach	Attach an independent disk to this virtual machine.	POST
disk:detach	Detach an independent disk from this virtual machine.	POST
down	References an object contained by this object.	GET
down:aclRules	Retrieve the ACL rules for this resource class action.	GET
down:apiDefinitions	Retrieve the API definitions for this extension service.	GET
down:apiFilters	Retrieve the API filters for this extension service.	GET
down:extensibility	Add an extension service to the system.	POST
down:fileDescriptors	Retrieve file descriptors for extension services APIs	GET
down:files	Retrieve files for extension services APIs	GET
down:resourceClassActions	Retrieve the actions defined for this extension service resource class.	GET
down:resourceClasses	Retrieve the resource classes defined by this extension service.	GET
down:serviceLinks	Retrieve the service links defined by this extension service.	GET
down:serviceResources	Retrieve the list of extension service resources of this class.
down:services	Retrieve the list of registered extension services.	GET
download:alternate	Reserved	N/A
download:default	References the default location from which this file can be downloaded.	GET
download:identity	References the extended OVF descriptor of this vApp template. The extended OVF descriptor contains additional information such as MAC address, BIOS UUID, and NetworkConfigSection	GET
edgeGateway:configureServices	Update the network services offered by this Edge Gateway.	POST
edgeGateway:reapplyServices	Reapply (after an update) the network services offered by this Edge Gateway.	POST
edgeGateway:redeploy	Redeploy the vShield Edge supporting this Edge Gateway.	POST
edgeGateway:syncSyslogSettings	Synchronize syslog server addresses used by this Edge Gateway with system defaults.	POST
edgeGateway:upgrade	Upgrade the backing configuration of this Edge Gateway from compact to full.	POST
edgeGateways	List the Edge Gateway objects in this organization VDC.	GET
edit	Modify this object, typically by replacing its current representation with the one in the request body.	PUT
enable	Enable this object.	POST
enterMaintenanceMode	Put this virtual machine into maintenance mode.	POST
entity	Retrieve a representation of the object on which an operation triggered this notification.	GET
entityResolver	Retrieve an object id as a context-free Entity element.	GET
event:create	Create an event in an this organization's event stream.	POST
exitMaintenanceMode	Take this virtual machine out of maintenance mode.	POST
fail	Fail this blocking task.	POST
firstPage	Reference to the first page of a paginated response.	GET
installVmwareTools	Install VMware Tools on this virtual machine.	POST
instantiate	Instantiate a VDC template to create a VDC in this organization.	POST
keystore:reset	Removes the keystore used by this service.	POST
keystore:update	Updates the keystore used by this service.	POST
keytab:reset	Removes the keytab used by this service.	POST
keytab:update	Updates the keytab used by this service.	POST
lastPage	Reference to the last page of a paginated response.	GET
media:ejectMedia	Eject virtual media from a virtual device.	POST
media:insertMedia	Insert virtual media into a virtual device.	POST
metrics	Retrieve a subset of current or historic metrics from a virtual machine	POST
merge	Merge one or more Provider VDCs with this Provider VDC.	POST
migrateVms	Migrate virtual machines from this resource pool to a different one.	POST
move	Reserved	N/A
nextPage	Reference to the next page of a paginated response.	GET
orgVdcNetworks	List the organization VDC networks supported by this Edge Gateway.	GET
ova	Reserved	N/A
ovf	References the OVF descriptor of this vApp template.	GET
power:powerOff	Power off this vApp or virtual machine.	POST
power:powerOn	Power on this vApp or virtual machine.	POST
power:reboot	Reboot this vApp or virtual machine.	POST
power:reset	Reset this vApp or virtual machine.	POST
power:shutdown	Shut down this vApp or virtual machine.	POST
power:suspend	Suspend this vApp or virtual machine.	POST
previousPage	Reference to the previous page of a paginated response.	GET
publish	Share this catalog.	POST
publishToExternalOrganizations	Publish this catalog externally	POST
recompose	Recompose this vApp to add, remove, or reconfigure virtual machines.	POST
reconfigureVm	Update multiple sections of a virtual machine.	POST
reconnect	Reconnect this vCenter Server to the system.	POST
refreshStorageProfiles	Refresh the list of storage profiles that exist on the vCenter service backing this Provider VDC.	POST
refreshVirtualCenter	Refresh the representation of this vCenter server	POST
register	Register a VCenter Server with the system.	POST
reloadFromVc	Reload certain properties of this virtual machine from the vCenter database.	POST
relocate	Relocate this virtual machine.	POST
remove	Remove this object.	DELETE
remove:force	Force removal of this object.	DELETE
repair	Repair this host or network.	POST
resourcePoolVmList	List the virtual machines using this resource pool.	GET
resume	Resume this blocking task.	POST
rights	List the service-specific rights created by this extension service.	GET
rights:cleanup	Remove service-specific rights no longer used by any extension service.	POST
screen:acquireTicket	Retrieve a screen ticket for this virtual machine.	GET
screen:thumbnail	Retrieve a thumbnail view of the screen of this virtual machine.	GET
shadowVms	List shadow virtual machines associated with the virtual machines in this vApp template.	GET
snapshot:create	Create a snapshot of the virtual machines in this vApp.	POST
snapshot:removeAll	Remove all snapshots created for the virtual machines in this vApp.	POST
snapshot:revertToCurrent	Revert all virtual machines in this vApp to their current snapshot.	POST
storageProfile	References the storage profile for this object.	GET
subscribeToExternalCatalog	Add an external subscription to this catalog.	POST
sync	Synchronize this catalog or catalog item with its external source.	POST
syncSyslogSettings	Synchronize syslog server addresses used by this vApp network with system defaults.	POST
takeOwnership	Take ownership of this user's vApps, media, and catalogs.	POST
task	Retrieve the blocking task that triggered this notification.	GET
task:cancel	Cancel this task.	POST
task:create	Create a task object.	POST
task:owner	Reference to the owner of a task.	GET
truststore:reset	Remove the truststore used by this service.	POST
truststore:update	Update the truststore used by this service.	PUT
undeploy	Undeploy this vApp.	POST
unlock	Unlock this user account.	POST
unregister	Unregister this vCenter Server.	POST
up	References an object that contains this object.	GET
update:resourcePools	Update the resource pools of this Provider VDC	POST
updateProgress	Request an update of this task's progress.	POST
upgrade	Upgrade this host.	POST
upload:alternate	Reserved	N/A
upload:default	References the default location to which this object can be uploaded.	PUT
vSphereWebClientUrl	A URL that you can use to view this object with the vSphere Web Client	GET

Related concepts

XML Representations in the vCloud API