7.2.3.  Searching Collections with Queries

A GET request on a "collection/search" link results in a search query of that collection. The API only returns resources within the collection that satisfy the search query constraints.
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>

7.2.3.1. Query Syntax

The API uses the URI templates to perform a search query with a GET request:
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
The query template value refers to the search query the API directs to the collection. This query uses the same format as Red Hat Enterprise Virtualization Manager search query language:
(criteria) [sortby (element) asc|desc]
The sortby clause is optional and only needed when ordering results.

Table 7.5. Example search queries

Collection Criteria Result
hosts vms.status=up Displays a list of all hosts running virtual machines that are up.
vms domain=qa.company.com Displays a list of all virtual machines running on the specified domain.
vms users.name=mary Displays a list of all virtual machines belonging to users with the username mary.
events severity>normal sortby time Displays the list of all events with severity higher than normal and sorted by the time element values.
events severity>normal sortby time desc Displays the list of all events with severity higher than normal and sorted by the time element values in descending order.

The API requires the query template to be URL-encoded to translate reserved characters, such as operators and spaces.

Example 7.2. URL-encoded search query

GET /api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml

Important

All search queries are case-sensitive.