7.4. Resources 7.4.1. Resources Resources are data sources in a RESTful web service. Each resource type contains a set of common parameters that the REST API abstracts to form a resource representation , usually in XML or JSON. Users can view a resource representation, then edit the parameters and send the representation back to the resource's URL within the API, which modifies the resource. Users can also delete individual resources through REST. A RESTful web service also groups resources into collections . Users can view a representation of all resources in a collection. Users also send resource representations to a specific collection to create a new resource within that particular collection. 7.4.2. Retrieving a Resource Obtain the state of a resource with a GET request on a URI obtained from a collection listing. Include an Accept HTTP header to define the MIME type for the response format. You can obtain additional information from some resources using the All-Content: true header. The RESTful Service Description Language describes which links support this header. 7.4.3. Updating a Resource Modify resource properties with a PUT request containing an updated description from a GET request for the resource URI. Details on modifiable properties are found in the individual resource type documentation. A PUT request requires a Content-Type header. This informs the API of the representation MIME type in the body content as part of the request. Include an Accept HTTP header to define the MIME type for the response format. This does not include immutable resource properties that an API user has attempted to modify. If an attempt is made to modify a strictly immutable resource property, the API reports a conflict with an error message representation in the response body. Properties omitted from the representation are ignored and not changed. 7.4.4. Deleting a Resource Delete a resource with a DELETE request sent to its URI. Include an Accept HTTP header to define the MIME type for the response format. Some cases require optional body content in the DELETE request to specify additional properties. A DELETE request with optional body content requires a Content-Type header to inform the API of the representation MIME type in the body content. If a DELETE request contains no body content, omit the Content-Type header. 7.4.5. Sub-Collection Relationships A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or has some meaning in the context of a parent resource. For example, a virtual machine contains network interfaces, which means the API maps the relationship between the virtual machine resource and the network interfaces sub-collection. Sub-collections are used to model the following relationships types: Where one parent resource can contain several child resources and vice versa. For example, a virtual machine can contain several disks and some disks are shared among multiple virtual machines. Where mapped resources are dependent on a parent resource. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and snapshots. Where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a cluster and a network. The API defines a relationship between a resource and a sub-collection using the link rel= attribute: The API user now queries the sub-collection. 7.4.6. XML Element Relationships XML element links act as an alternative to sub-collections to express relationships between resources. XML element links are simply elements with a "href" attribute that points to the linked element. XML element links are used to model simple 1:N mappings between resources without a dependency and without data associated with the relationship. For example, the relationship between a host and a cluster. Examples of such relationships include: Backlinks from a resource in a sub-collection to a parent resource; or Links between resources with an arbitrary relationship. Example 7.7. Backlinking from a sub-collection resource to a resource using an XML element 7.4.7. Actions Most resources include a list of action links to provide functions not achieved through the standard HTTP methods. The API invokes an action with a POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and task-specific parameters. Table 7.6. Common action parameters Element Description async true if the server responds immediately with 202 Accepted and an action representation contains a href link to be polled for completion. grace_period a grace period in milliseconds, which must expire before the action is initiated. Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a fault response. An action also requires a Content-Type: application/xml header since the POST request requires an XML representation in the body content. When the action is initiated asynchronously, the immediate 202 Accepted response provides a link to monitor the status of the task: A subsequent GET on the action URI provides an indication of the status of the asynchronous task. Table 7.7. Action statuses Status Description pending Task has not yet started. in_progress Task is in operation. complete Task completed successfully. failed Task failed. The returned action representation would contain a fault describing the failure. Once the task has completed, the action is retained for an indeterminate period. Once this has expired, subsequent GET s are 301 Moved Permanently redirected back to the target resource. An action representation also includes some links that are identified by the rel attribute: Table 7.8. Action relationships Type Description parent A link back to the resource of this action. replay A link back to the original action URI. POSTing to this URI causes the action to be re-initiated. 7.4.8. Permissions Each resource contains a permissions sub-collection. Each permission contains a user , an assigned role and the specified resource. For example: A resource acquires a new permission when an API user sends a POST request with a permission representation and a Content-Type: application/xml header to the resource's permissions sub-collection. Each new permission requires a role and a user : 7.4.9. Handling Errors Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a fault representation in the response entity body. The fault contains a reason and detail strings. Clients must accommodate failed requests via extracting the fault or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.

Commands:
GET /ovirt-engine/api/ [collection] / [resource_id] HTTP/1.1 Accept: [MIME type]
GET /ovirt-engine/api/ [collection] / [resource_id] HTTP/1.1 Accept: [MIME type] All-Content: true
PUT /ovirt-engine/api/ collection / resource_id HTTP/1.1 Accept: [MIME type] Content-Type: [MIME type] [body]
DELETE /ovirt-engine/api/ [collection] / [resource_id] HTTP/1.1 Accept: [MIME type]
GET /ovirt-engine/api/collection/resource_id HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"> <link rel="subcollection" href="/ovirt-engine/api/collection/resource_id/subcollection"/> </resource>
GET /ovirt-engine/api/collection/resource_id/subcollection HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <subcollection> <subresource id="subresource_id" href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id"> </subresource> </subcollection>
GET /ovirt-engine/api/collection/resource_id/subcollection/subresource_id HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/xml <subcollection> <subresource id="subresource_id" href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id"> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> </subresource> </subcollection>
<resource> <actions> <link rel="start" href="/ovirt-engine/api/collection/resource_id/start"/> <link rel="stop" href="/ovirt-engine/api/collection/resource_id/stop"/> </actions> </resource>
POST /ovirt-engine/api/collection/resource_id/action HTTP/1.1 Content-Type: application/xml Accept: application/xml <action> <async>true</async> </action> HTTP/1.1 202 Accepted Content-Type: application/xml <action id="action_id" href="/ovirt-engine/api/collection/resource_id/action/action_id"> <async>true</async> </action>
GET /ovirt-engine/api/collection/resource_id/action/action_id HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <action id="action_id" href="/ovirt-engine/api/collection/resource_id/action/action_id"> <status> <state>pending</state> </status> <link rel="parent" /ovirt-engine/api/collection/resource_id"/> <link rel="replay" href="/ovirt-engine/api/collection/resource_id/action"/> </action>
GET /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1 Accept: application/xml HTTP/1.1 200 OK Content-Type: application/xml <permissions> <permission id="permission-id" href="/ovirt-engine/api/collection/resource_id/permissions/permission_id"> <role id="role_id" href="/ovirt-engine/api/roles/role_id"/> <user id="user_id" href="/ovirt-engine/api/users/user_id"/> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> </permission> </permissions>
POST /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1 Content-Type: application/xml Accept: application/xml <permission> <role id="role_id"/> <user id="user_id"/> </permission> HTTP/1.1 201 Created Content-Type: application/xml <permission id="permission_id" href="/ovirt-engine/api/resources/resource_id/permissions/permission_id"> <role id="role_id" href="/ovirt-engine/api/roles/role_id"/> <user id="user_id" href="/ovirt-engine/api/users/user_id"/> <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/> </permission>
PUT /ovirt-engine/api/collection/resource_id HTTP/1.1 Accept: application/xml Content-Type: application/xml <resource> <id>id-update-test</id> </resource> HTTP/1.1 409 Conflict Content-Type: application/xml <fault> <reason>Broken immutability constraint</reason> <detail>Attempt to set immutable field: id</detail> </fault>