Chapter 20. Tags

The tags collection provides information about tags in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="tags" link obtained from the entry point URI (see Chapter 4, Entry Point).
The following table shows specific elements contained in a tag resource representation.

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 20.1. Tag elements

Element Type Description Properties
host GUID A reference to the host which the tag is attached. See Chapter 12, Hosts.
user GUID A reference to the user which the tag is attached. See Chapter 19, Users.
vm GUID A reference to the VM which the tag is attached. See Chapter 13, Virtual Machines.
parent complex A reference to the VM which the tag is attached.

Example 20.1. An XML representation of a tag resource

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <parent>
        <tag id="-1" href="/api/tags/-1"/>
    </parent>
</tag>

Creation of a new tag requires the name element. The name, description and parent elements are updatable post-creation.

20.1. Associating Tags With a Host, User or VM

The collection referenced by link rel="tags" from a host, user or vms represents the set of tags associated with the entity.
The tag representations are as described in Chapter 20, Tags, except they also contain a host id, user id or vm id reference to the entity in question.
Each tags collection is manipulated as described in Chapter 7, Common Features. Associating a tag with an entity is achieved by POSTing a tag reference (identifying the tag either by its id or name) to the collection.

Example 20.2. Associating a tag with a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <name>Finance</name>
</tag>

HTTP/1.1 201 Created
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
  f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

Removing an association is achieved with a DELETE request to the appropriate element in the collection.

Example 20.3. Removing a tag from a virtual machine

DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1

HTTP/1.1 204 No Content

To query the set of entities associated with a given tag, the collection/search URI template for the appropriate collection should be used to search for entities matching tag=MyTag.

Example 20.4. Querying a collection for tagged resources

GET /api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<vms>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>