Product SiteDocumentation Site

Chapter 7. Common Features

7.1. Representations
7.2. Collections
7.2.1. Listing All Resources in a Collection
7.2.2. Listing Extended Resource Sub-Collections
7.2.3. Searching Collections with Queries
7.2.4. Creating a Resource in a Collection
7.3. Resources
7.3.1. Retrieving a Resource
7.3.2. Updating a Resource
7.3.3. Deleting a Resource
7.3.4. Sub-Collection Relationships
7.3.5. XML Element Relationships
7.3.6. Actions
7.3.7. Permissions
7.3.8. Handling Errors
This chapter examines features common to resources and collections.

Note

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 7.1, “Element property icons”
Table 7.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. Include these elements in a client-provided representation on update only if their values are not altered by the API user. If altered, the API reports an error.
Read-only These elements are read-only. Values for read-only elements are not created or modified.

7.1. Representations

The API structures resource representations in the following XML document structure:
<resource id="resource_id" href="/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="/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprise Linux 6 Virtual Machine</description>
    ...
</vm>
All resource representations contain a set of common attributes
Table 7.2. Common attributes to resource representations
Attribute Type Description Properties
id GUID Each resource in the virtualization infrastructure contains an id, which acts as a globally unique identifier (GUID). The GUID is the primary method of resource identification.
href string The canonical location of the resource as an absolute path.

All resource representations contain a set of common elements.
Table 7.3. Common elements to resource representations
Element Type Description Properties
name string A user-supplied human readable name for the resource. The name is unique across all resources of its type.
description string A free-form user-supplied human readable description of the resource.