Product SiteDocumentation Site

Chapter 8. Common Features

8.1. Representations
8.2. Collections
8.2.1. Listing All Resources in a Collection
8.2.2. Listing Extended Resource Sub-Collections
8.2.3. Search Queries
8.3. Resources
8.3.1. Retrieving a Resource
8.3.2. Creating a Resource
8.3.3. Creating a Resource Asynchronously
8.3.4. Updating a Resource
8.3.5. Deleting a Resource
8.3.6. Sub-Collection Relationships
8.3.7. XML Element Relationships
8.3.8. Actions
8.3.9. Permissions
8.3.10. Handling Errors
This chapter examines features common to resources and collections.

Element property icons

Throughout this guide, the elements of each resource are detailed in tables. These tables include a properties column, displaying icons depicting element properties. The meaning of these icons is shown in Table 8.1, “Element property icons”
Table 8.1. Element property icons
Property Description Icon
Required for creation These elements must be included in the client-provided representation of a resource on creation, but are not mandatory for an update of a resource.
Non-updateable These elements cannot have their value changed when updating a resource. They are only included in a client-provided representation on update if their values are not altered. Otherwise they are omitted from an update action.
Read-only These elements are read-only. Values for read-only elements are not created or modified.

8.1. Representations

The API structures resource representations in the following XML document structure:
<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>Resource-Name</name>
    <description>A description of the resource</description>
    ...
</{resource}>
In the context of a virtual machine, the representation appears as follows:
<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
  href="/rhevm-api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprize Linux 6 Virtual Machine</description>
    ...
</vm>
The following attributes are common to all resource descriptions:
Element Type Description Properties
id GUID An opaque server-generated identifier for the resource, which is guaranteed to be unique across all resources in this Red Hat Enterprise Virtualization Manager instance
href string The canonical location of the resource as an absolute path