The vCloud API represents objects as XML documents in which object properties appear as elements and attributes with typed values. The object hierarchy is defined by an XML schema.

XML representations of first-class vCloud API objects, such as the objects in vCloud API Object Taxonomy, include these attributes.

id

The object identifier, expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused. The id attribute value is intended to provide a context-free identifier that can be used with the vCloud API entityResolver (see Retrieve an Object as an Entity).

type

The object type, specified as a MIME content type.

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.

Views

The vCloud API defines several contexts, or views, in which you can access objects in a cloud. These views are expressed in the URL returned as the href of an object, and have the following forms, where API-URL is a URL of the form https://vcloud.example.com/api and object-type is a string indicating the type of the object.

user view

A URL of the form API-URL/object-type/id indicates that any user can access the object.

admin view

A URL of the form API-URL/admin/object-type/id indicates that organization administrators and system administrators can access the object. Organization administrators do not have rights to modify some objects in the admin view.

extension view

A URL of the form API-URL/admin/extension/object-type/id indicates that system administrators can access the object.

A given object retrieved in one view may have a different representation and media type from the same object retrieved in a different view. Not all objects are presented in every view.

Example: Object id, type, and href Attributes

These abbreviated request and response examples show the id, type, and href attributes in the user and admin views of an organization.

Request: 

GET https://vcloud.example.com/api/org/72fe715c-5f6a-407f-bbb2-bf465915b5f4

Response: 

<Org
   ...
   id="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
   type="application/vnd.vmware.vcloud.org+xml"
   href="https://vcloud.example.com/api/org/72fe715c-5f6a-407f-bbb2-bf465915b5f4"
   ...>
   ...
</Org>

The id value is the same in both cases, but the type and href attributes have values specific to the view.

Request: 

GET https://vcloud.example.com/api/admin/org/72fe715c-5f6a-407f-bbb2-bf465915b5f4

Response: 

<AdminOrg
   ...
   id="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
   type="application/vnd.vmware.admin.organization+xml"
   href="https://vcloud.example.com/api/admin/org/72fe715c-5f6a-407f-bbb2-bf465915b5f4"
   ...>
   ...
</AdminOrg>

The value of the id attribute is a permanent, unique object identifier. The value of the href attribute is an object locator that refers to a specific view of the object in its current location. Unlike the value of the id attribute, object location and view context can change during the life of an object. The example in Example: Using the entityResolver URL shows how to retrieve this object as entity.

When a client application must keep a persistent reference to an object, the best practice is to keep a reference to the id and the href (URL) that was most recently used to access the object. When the application needs to access the object in the future, it should first try using the saved href. If that fails, use the id with the entity resolver to obtain a valid reference to the object, then replace the saved href with that valid reference.