7.2. Collections
A collection is a set of resources of the same type. The API provides both top-level collections and sub-collections. This section examines common features for collections.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
7.2.1. Listing All Resources in a Collection
A listing of the resources in a collection is obtained by issuing a
GET request on the collection URI obtained from the entry point.
GET /api/[collection] 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">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
...
</collection>
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
7.2.2. Listing Extended Resource Sub-Collections
The API extends collection representations to include sub-collections when the
Accept header includes the detail parameter.
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection
This includes multiple sub-collection requests using either separated
detail parameters:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1; detail=subcollection2
Or one
detail parameter that separates the sub-collection with the + operator:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
The API supports extended sub-collections for the following main collections.
| Collection | Extended Sub-Collection Support |
|---|---|
hosts | statistics |
bricks | statistics |
step | statistics |
Example 7.1. An request for extended statistics in the servers collection
GET /api/hosts HTTP/1.1 Accept: application/xml; detail=statistics
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
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>
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
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 Storage Console search query language:
(criteria) [sortby (element) asc|desc]
The
sortby clause is optional and only needed when ordering results.
| Collection | Criteria | Result |
|---|---|---|
volumes | type=REPLICATE | Displays a list of all replicate volumes |
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/events?search=severity%3Derror HTTP/1.1 Accept: application/xml
Important
All search queries are case-sensitive.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
7.2.3.2. Wildcards
Search queries substitute part of a value with an asterisk as a wildcard.
Example 7.3. Wildcard search query for name=server*
GET /api/hosts?search=name%3Dserver* HTTP/1.1 Accept: application/xml
This query would result in all servers with names beginning with
server, such as server-1, server-2, or server-data.
Example 7.4. Wildcard search query for name=s*1
GET /api/hosts?search=name%3D*1 HTTP/1.1 Accept: application/xml
This query would result in all servers with names beginning with
s and ending with 1, such as server1 or server-1 .
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A3522632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
7.2.3.3. Pagination
Some Red Hat Storage environments contain large collections of resources. However, the API only displays a default number of resources for one search query to a collection. To display more than the default, the API separates collections into pages via a search query containing the
page command.
Example 7.5. Paginating resources
This example paginates resources in a collection. The URL-encoded request is:
GET /api/collection?search=page%201 HTTP/1.1 Accept: application/xml
Increase the
page value to view the next page of results.
GET /api/collection?search=page%202 HTTP/1.1 Accept: application/xml
Use the
page command also in conjunction with other commands in a search query. For example:
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1 Accept: application/xml
This query displays the second page in a collection listing ordered by a chosen element.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
7.2.4. Creating a Resource in a Collection
The API creates a new resource with a
POST request to the collection URI containing a representation of the new resource.
A
POST request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
Each resource type has its own specific required properties. The client supplies these properties as XML elements when creating a new resource. Refer to the individual resource type documentation for more details. If a required property is absent, the creation fails with a
fault representation indicating the missing elements.
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<name>Resource-Name</name>
</resource>
HTTP/1.1 201 Created
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
...
</resource>
The
Location header in the response gives the URI of the queried resource. The response body contains either a complete representation, partial representation or no representation of the resource. It is recommended that clients rely only on fetching the representation via the URI in the response header.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
